To enable or disable a registered application:

1. Go to Administration > Global settings > API Integration Applications.

2. Click the ENABLE or DISABLE link in the top right corner of the corresponding box. A confirmation dialog box appears.

3. Click ENABLE or DISABLE to enable or disable the application. Click Cancel to cancel the operation and return to the API Integration Applications screen.

Application Configuration

You can view the configuration details of your registered applications, including their unique Client ID from the Application Configuration form. You can change the application name, description or Redirect URI or generate a new Client Secret for the application.

To open the Application Configuration screen for a registered application, go to Administration > Global settings > API Integration Applications and click the edit icon in the bottom right corner of the corresponding box.

1. The General section of the form lists the main application detail:

   • You can change the Application name, Description and Redirect URI.

   • You can view when the application was registered under Created.

   Note: All times are given as Eastern Standard Time (EST).

2. You can view the Client ID — the unique identifier a client application needs to send to OpenAir along with a client secret as part of the OAuth 2.0 authorization code flow.

3. The Tokens Lifetime section of the form indicates the validity period of the access and refresh tokens — Access token lifetime and Refresh token lifetime.

   As part of the Auth 2.0 authorization code flow, authorized applications need to exchange an authorization code for an access token and refresh token to obtain access to OpenAir. The access token has a short expiration time. When the access token expires, the client application can use the refresh token to obtain a new access token without user interaction until the refresh token expires or the authorization is revoked. A new refresh token is returned with the access token if the current refresh token is due to expire before the new access token expires.

4. To generate a new Client Secret, click Regenerate Secret — You may need to generate a new client secret if you misplace or delete the client secret accidentally or if your client secret becomes compromised.

   The new client secret will be valid immediately. The old client secret will continue to be valid for 24 hours after you generate a new one. This allows time to update any enabled application with the new client secret.

5. If you made any changes to the configuration details in the General section, the Save button is enabled. Click Save to save changes and return to the API Integration Applications screen or click Cancel to close the configuration form without saving.

OAuth 2.0 for Integration Applications Developers

OpenAir supports two methods to access OpenAir data using OpenAir XML or SOAP API requests:

• Using user credentials (Company ID, User ID, password) and, in the case of OpenAir SOAP web services, a session ID.

• Using OAuth 2.0 access tokens.

In the OAuth 2.0 scenario, client applications use one of the OAuth 2.0 grant types to get an access token after the user authorizes the application. The user’s identity is verified by an authentication service, which issues the access token. The access token can then be used to gain authenticated access to OpenAir through the XMl or SOAP API.

This section describes how to get an access token using the OAuth 2.0 authorization code grant type in your applications, and how to use the access token in your API calls.

Note: OpenAir only supports the OAuth 2.0 authorization code grant type, which defines a particular workflow client applications can use to obtain the access token.

OAuth 2.0 Authorization Code Flow

Application developers can use the OAuth 2.0 redirection-based authorization code grant type to obtain an access token. This method eliminates the need for client applications to collect and store user credentials.

The authorization code flow includes the following steps:

1. Getting the user’s explicit permission to access OpenAir on their behalf.

   1. The client application opens a browser and directs the user to the OpenAir identity authentication service with the necessary URL query string parameters.

   2. The user enters user credentials in the OpenAir login form or in a third-party identity provider Single Sign-on login form . The authenticated user is then prompted to authorize the application’s access request.

2. Receiving the authorization code — OpenAir issues an authorization code. The user is redirected back to the client application with the authorization code in the query string.

3. Exchanging the authorization code for an access token — The client application must exchange the authorization code for an access token and a refresh token.

An additional step — Refreshing an access token — is required to get a new access token after the previously issued access token has expired.

Getting the User’s Permission

To begin the OAuth 2.0 authorization code flow, the client application must direct the user to the authorization server — OpenAir — using a GET request.

Send a GET request to the authorization endpoint using a URL like the following:

https://company-id.app.openair.com/login/oauth2/v1/authorize?response_type=code&redirect_uri=https://example-app.com/redirect&client_id=174_h1FiXfWsJtLJG0DG&scope=soap&state=ryjp37y2qa28hdseck1gat

The GET request URL includes the authorization endpoint for the OpenAir account followed by a query string: https://<company-id>.app.openair.com/login/oauth2/v1/authorize?<query-string>.

The request parameters are described in the following table.

Request parameter	Description
response_type	The value of the response_type parameter is always code. It tells the authorization server that the client application is initiating the OAuth 2.0 authorization code flow.
redirect_uri	The valid redirect URI where the application will process the authorization code. The user should be redirected to this URI after allowing or denying the access request. The redirect URI must match the redirect URI specified on the application configuration form in OpenAir.
client_id	The public identifier for the client application. The Client ID is generated by OpenAir when an administrator registers the client application.
scope	The scope for which the application is requesting access. The scope determines which OpenAir API the application will be able to access. OpenAir currently supports the following scopes: xml, soap. OpenAir only accepts a single scope value. The scope value is case insensitive. Authorized applications have the same permissions and data access privileges as the user authorizing the application within the selected scope.
state	A random string generated by the client application, which is used to prevent cross-site request forgery (CSRF) attacks. For more information see the OAuth 2.0 specification RFC6749 Section 10.12.

After the application sends the GET request, OpenAir redirects the user to the OpenAir login form. OpenAir may redirect the user to a third-party Identity provider Single Sign-on form, if SAML SSO is enabled for the account and the user. After successful authentication, OpenAir displays an authorization screen prompting the user to approve the application’s access request.

Receiving the Authorization Code

After obtaining the user’s explicit permission, OpenAir initiates a redirect to the redirect URI specified in the GET request with the authorization code and the state as query parameters.

The redirect query parameters are described in the following table.

Redirect parameter	Description
state	The client application should check that the state in the redirect matches the state set in the GET request initiating the OAuth 2.0 authorization code flow. Validating the state sent to and returned from the authorization server can be used to prevent cross-site request forgery (CSRF) attacks.
code	The authorization code issued by OpenAir. It is a unique single use code issued only for the client application requesting access. The authorization code is valid for 10 minutes. The client application must exchange the authorization code for an access token before the authorization expires.

The following sample redirects illustrate successful and unsuccessful authorization.

• Application successfully authorized.

  https://example-app.com/redirect?state=ryjp37y2qa28hdseck1gat&code=JTlQ43UvYDKbhI_SpEWsIE_bTpbou2-kYeeLtKiMuR1iqZ3W3roqM4rmRC8fFCOJtBI6a85AnJPefx2szW9g4jCY

• Application not authorized.

  https://example-app.com/redirect?error_description=The+resource+owner+or+authorization+server+denied+the+request&error=access_denied&state=ryjp37y2qa28hdseck1gat

Exchanging the Authorization Code for an Access Token

The application can use the authorization code to obtain an access token and a refresh token using a POST request.

Send a POST request to the token endpoint.

• The POST request URL is https://<company-id>.app.openair.com/login/oauth2/v1/token

• The request must include the client ID and the client secret in the HTTP authorization request header.

  • The client authentication method used in a header of the request follows the HTTP Basic authentication scheme. For more information, see RFC 7617.

  • The format is client_id:clientsecret.

  • The string value is Base64 encoded.

• The request must include the parameters grant_type, code and redirect_uri in the request body.

  • Request parameters must be encoded based on the HTML specification for application/x-www-form-urlencoded media type. For more information, see URL Specification 5.1.

The request parameters are described in the following table.

Request parameter	Description
grant_type	The value of the grant_type parameter is authorization_code. It tells the token endpoint that the client application is using the OAuth 2.0 authorization code grant type.
code	The authorization code issued by OpenAir and received by the client application in the redirect.
redirect_uri	The valid redirect URI. The redirect URI must match the redirect URI specified on the application configuration form in OpenAir and when requesting the authorization code.
client_id	The public identifier for the client application. The Client ID is generated by OpenAir when an administrator registers the client application.
client_secret	The client secret for the application. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.

Example POST request:

POST /login/oauth2/v1/token HTTP/1.1 Host: company-id.app.openair.com Authorization: Basic MTc0X2gxRmlYZldzSnRMSkcwREc6dmNGVGFORTNuVVhSdUoyOWpoRWxYU0g3THBYd2J4VEdkbUpIb1FNdm9fano0dmxkT0ZQSVRGSi1aRlRvWVIyRzZnbmwwZHFYZWVpRlVJb0tuUkdTZlEK Content-Type: application/x-www-form-urlencoded code=JTlQ43UvYDKbhI_SpEWsIE_bTpbou2-kYeeLtKiMuR1iqZ3W3roqM4rmRC8fFCOJtBI6a85AnJPefx2szW9g4jCY&redirect_uri=https%3A%2F%2Fexample-app.com%2Fredirect&grant_type=authorization_code

The token endpoint will verify all the parameters in the request to ensure that the authorization code is valid and that the client ID and client secret match. If all the request headers and parameters are valid, the token endpoint generates an access token and refresh token and includes them in the response.

The token endpoint returns the response as a JSON object with the properties described in the following table.

JSON object properties	Description
access_token	The access token in JSON Web Token (JWT) format. The access token is valid for 15 minutes.
refresh_token	The refresh token in JSON JWT format. The refresh token is valid for 24 hours.
expires_in	The access token expiration time in seconds. The access token is valid for 900 seconds after it is issued.
type	The value of the type property is always bearer. For more information, see the OAuth 2.0 specification — RFC 6750.

Example response (successful token request):

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "refresh_token":"WGxpeGNVTm1mNGhaS2E1djFQQ2twV1pKcWpOU0pXUkhZUU5oMTR1MFU5OUtLY3N1NkZKOG9SMHp4UnNuMjYyRTJGcm9NVUo5OWxENDFzcW5WSDFsUEhoSF8xNzQ", "expires_in":900, "access_token":"eNNJ1GXD25-6IUylF6RZT33HqhoqSAAK53F0kxT62fBoKreDoc8Y_-Gnk2lUIqNbhwguHnxDtxUsJMY6NrDoiBnd", "token_type":"bearer" }

The client application can now use the access token to make API requests. This completes the authorization flow.

The access token is only valid for a short period of time and within the scope it was issued for. The client application will need to refresh the access token to continue making API requests after it expires.

Refreshing an Access Token

The access token has a short expiration time (15 minutes). When the access token expires, the client application can use the refresh token to obtain a new access token using a POST request.

• You can use the expiration time value (expires_in) to refresh access tokens before it is due to expire.

• You can refresh access token if an API request returns an authentication failed error.

Send a POST request to the OpenAir token endpoint. The POST request is similar to that used to exchange an authorization code for an access token except it now uses the parameters set in the following table.

Request parameter	Description
grant_type	The value of the grant_type parameter is refresh_token. It tells the token endpoint that the client application is requesting to refresh an access token.
refresh_token	A valid refresh_token. Refresh tokens are valid for 24 hours.
redirect_uri	The valid redirect URI.
client_id	The public identifier for the client application.
client_secret	The client secret for the application.

Example POST request:

POST /login/oauth2/v1/token HTTP/1.1 Host: company-id.app.openair.com Authorization: Basic MTc0X2gxRmlYZldzSnRMSkcwREc6dmNGVGFORTNuVVhSdUoyOWpoRWxYU0g3THBYd2J4VEdkbUpIb1FNdm9fano0dmxkT0ZQSVRGSi1aRlRvWVIyRzZnbmwwZHFYZWVpRlVJb0tuUkdTZlEK Content-Type: application/x-www-form-urlencoded refresh_token=WGxpeGNVTm1mNGhaS2E1djFQQ2twV1pKcWpOU0pXUkhZUU5oMTR1MFU5OUtLY3N1NkZKOG9SMHp4UnNuMjYyRTJGcm9NVUo5OWxENDFzcW5WSDFsUEhoSF8xNzQ&redirect_uri=https%3A%2F%2Fexample-app.com%2Fredirect&grant_type=refresh_token

The token endpoint will verify all the parameters in the request to ensure that the refresh token is valid and that the client ID and client secret match. If all the request headers and parameters are valid, the token endpoint generates an access token and refresh token and includes them in the response.

The token endpoint returns the response as a JSON object with the properties described in the following table. The response includes both a new access token and a new refresh token.

JSON object properties	Description
access_token	The access token in JSON Web Token (JWT) format. The access token is valid for 15 minutes.
refresh_token	The refresh token in JSON JWT format. The refresh token is valid for 24 hours.
expires_in	The access token expiration time in seconds. The access token is valid for 900 seconds after it is issued.
type	The value of the type property is always bearer. For more information, see the OAuth 2.0 specification — RFC 6750.

Example response (successful token request):

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "refresh_token":"N25RdE82N0FIMnBDRTQ1d3hITHN6dXRwQ3dNdzVHWHMydWd3WWFqUXMwMWgrcTB3UHBFQ3VLaUZQTlRuR0J3U09LaWcvWWJ2UHpPS2hWUUtxQlJCMzBHVF8xNzQ", "expires_in":900, "access_token":"pWprqUHkgaOWai7fSjaNaN5ywpDr7a7W6hLiq-b1vBBAT48zxAPTyy-wpTNxyfwJieQzZ5E1HEOsG1hNtwJpILR5", "token_type":"bearer" }

Token Request Errors

Your client application needs to handle the following cases when the request to exchange an authorization code for an access token or to refresh a token fails. The token endpoint may return one of the errors listed in the following table if the token request fails.

• Errors are listed in descending priority order. Only the first error is returned if there are more than one.

• Some of the errors are specific to one of the two possible types of request ( grant_type).

error	error_description	grant_type	Reason
unsupported_grant_type	The authorization grant type is not supported by the authorization server		The grant_type must be either authorization_code or refresh_token.
invalid_request	Authorization header not sent		Request headers must include a Basic Authorization header.
invalid_request	No credentials provided		The Client Id and Client Secret must be sent in the request Authorization header.
access_denied	Authorization code is not valid	authorization_code	The authorization code must be valid. Possible reasons include: Expired authorization code — The authorization code is valid for 10 minutes. Authorization revoked — Users can revoke an application at any time. Disabled application — Account administrators can disable an application at any time.
invalid_request	redirect_uri or client_id is not valid	authorization_code	The redirect URI and Client ID must match the information specified on the application configuration form in OpenAir.
access_denied	Refresh token is not valid	refresh_token	The refresh token sent in the request is not valid. Possible reasons include: Expired refresh token — Refresh tokens are valid for 24 hours. Authorization revoked — Users can revoke an application at any time. Disabled application — Account administrators can disable an application at any time.
invalid_scope	Changing scopes is not supported	refresh_token	Tokens are issued for a specific scope. The scope of the token requested must be the same as the scope of the token sent in the request.
access_denied	Authorization failed		The Client Id and Client Secret pair sent in the request is not valid. Note that account administrators may generate a new Client Secret for the application in OpenAir.

Note: If applicable, the client application can initiate the OAuth 2.0 authorization code flow again to obtain a new authorization code and exchange it for an access token. The end user will be directed to the login form and required to enter valid user credentials. If the user revoked the application the authorization screen will appear. If the application is still authorized, the authorization endpoint will return a new authorization code immediately after the successful user authentication.

Using OAuth 2.0 Access Tokens in Your API Requests

You can use OAuth 2.0 access token authorization instead of password authentication or Session ID in your API requests. Both OpenAir XML API and OpenAir SOAP API support authorization using access tokens.

Note: Both OpenAir XML API and OpenAir SOAP API continue to support password authentication. OpenAir SOAP API continues to support SessionID.

Authorization Errors

API requests must use a valid access token. OpenAir API return an error code 420 and message Authentication failed otherwise.

• The access token must exist.

• The access token must not be expired.

• The user who gave the application permission to access OpenAir must be active. The same access token can be used if the user is set to active again.

• The application must be enabled for the OpenAir account. The same access token can be used if the application is disabled and then enabled again.

API requests must use an access token with a valid scope. OpenAir API return an error code 413 and message Account not privileged to access API otherwise.

• The access token must be used within the scope (the specific OpenAir API) it was issued for. For example, an invalid scope error will be returned if the authorization code was obtained for the scope xml and the client application attempts to use the access token in a SOAP API request.

An invalid OAuth2 access token authorization has priority over a valid password authentication. You cannot use password authentication (Company ID, User ID, password) — or a valid Session ID in the SOAP session header — as a fallback for an invalid access token.

Using OAuth2.0 Access Tokens to Make XML API Requests

The access token (access_token) is passed instead of Company ID, User ID and Password used for password authentication in the Auth XML command.

Use the syntax given in the following example:

<Auth> <Login> <access_token>eNNJ1GXD25-6IUylF6RZT33HqhoqSAAK53F0kxT62fBoKreDoc8Y_-Gnk2lUIqNbhwguHnxDtxUsJMY6NrDoiBnd</access_token> </Login> </Auth>

Using OAuth2.0 Access Tokens to Make SOAP API Requests

The access token (accessToken) is held in the SessionHeader web services method complex type instead of the logged in user Session ID (sessionId). Use the syntax given in the following examples:

XML Example

<SessionHeader xsi:type="perl:SessionHeader"mlns:perl="http://namespaces.soaplite.com/perl"> <accessToken xsi:type="xsd:string">eNNJ1GXD25-6IUylF6RZT33HqhoqSAAK53F0kxT62fBoKreDoc8Y_-Gnk2lUIqNbhwguHnxDtxUsJMY6NrDoiBnd</accessToken> </SessionHeader>

C# Example

// Create service stub OAirServiceHandlerService _svc = new OAirServiceHandlerService(); // POST Request to get access_token // Create a new session header object and add the access token _svc.SessionHeaderValue = new SessionHeader(); _svc.SessionHeaderValue.accessToken = response.access_token;

Java Example

// Set the service URL OAirServiceHandlerServiceLocator locator = new OAirServiceHandlerServiceLocator(); locator.setOAirServiceAddress("https://company-id.app.openair.com/soap"); // POST Request to get access_token // Create a new session header object and add the access token SOAPHeaderElement header = new SOAPHeaderElement("https://company-id.app.openair.com/OAirService", "SessionHeader"); SOAPElement node = header.addChildElement("accessToken"); node.addTextNode(access_token); binding.setHeader(header);

Authorizing Applications to Access OpenAir on Your Behalf

Integration applications let you connect OpenAir with other applications and they extend what you can do with OpenAir. Integration applications may use the OAuth 2.0 authorization protocol to gain access to your OpenAir account.

The first time an application using the OAuth 2.0 protocol attempts to access OpenAir on your behalf, you will need to give this application your explicit permission.

1. The application will open a browser and direct you to the same trusted login form you normally use to log into OpenAir. The OpenAir login form or your company Single Sign-on form will appear.

2. Enter your login details and click Log in. An authorization screen will appear indicating that the application <application name> would like to access your OpenAir data.

3. Read the content of the authorization screen attentively. It should describe what the application does and how it will help you. It should also say what the application can do:

   • The application will be able to access all data you have access to.

   • The application will be able to perform all actions permitted by your role and user privileges.

4. Click ALLOW to authorize the application or click CANCEL if you do not want the application to access OpenAir on your behalf.

Integration applications are registered and managed by your account administrator. They need to be enabled on your account before they can attempt to connect to OpenAir and request your permission.

Note: Integration applications are registered and managed by your account administrator. They need to be enabled on your OpenAir account before they can attempt to connect to OpenAir and request your permission.

Account administrators can disable an application at any time.

• If you have authorized an application and this application is disabled by an administrator, the application will no longer be able to interact with OpenAir.

• If an administrator enables this application again, you will need to give this application your explicit permission again before you can continue to work with it in connection with OpenAir.

After you authorize an application, it will be able to interact with OpenAir on your behalf until you revoke the authorization.

To view the application you have authorized, go to User Center > Personal Settings > Authorized Applications. All your authorized applications are listed in a grid. Details include the name of the application and the date and time when it was last updated.

Note: All times are given as Eastern Standard Time (EST).

To revoke an application, click REVOKE in the top right corner of the corresponding box, then click REVOKE in the confirmation message. The application no longer shows in the authorized applications list. If a revoked application attempts to access OpenAir on your behalf, you will be prompted to give this application your explicit permission again.

API Support for Job Code Used

Read information about which tables use job codes using the XML API and SOAP API.

Read the JobCodeUsed type using the XML API or SOAP API. The JobCodeUsed type includes the following fields: id, table_name, used_by , position , created, updated.

API Support for Booking Type in Resource Request Queue

Read and modify the booking type when reading, adding or modifying Resource Request Queue records using the XML API and SOAP API.

The booking_type_id field is available when using the XML API or SOAP API to read, add, modify records in the ResourceRequestQueue table.

Platform Solutions Catalog

Download and read about real world use case script examples from the new Platform Solutions page in the OpenAir Help Center.

To view the platform solutions catalog, go to User Center > Help Center > Platform Solutions. The page lists all the real world user scripting examples described in the OpenAir User Scripting Guide. Solutions are color coded by category — Validation, Automation, Workflow — with a visual representation and a short summary to indicate the purpose of each solution.

To save the solution XML file, click the DOWNLOAD link. You can then import the solution file from the Scripting Center in OpenAir.

To read the help topic describing the solution, click the LEARN MORE link.

Note: The OpenAir Help Center feature must be enabled for your account and you must be an administrator or have the "View Help Center" role permission to access the Platform Solutions page. The OpenAir Scripting Center feature must be enabled for your account and you must be an administrator or have the "View Scripting Center" role permission to access the import solution files and try out the solutions.

Data Dictionary Link in OpenAir Help Center

Click the Data Dictionary tab in the Help Center navigation bar to open the OpenAir Data Dictionary in a new browser tab or window.

Scripting Support for Reading Published List View Data

Use published list views like custom queries and read the latest list view data in your OpenAir form and scheduled scripts.

Read your published list view data in your OpenAir form scripts and scheduled scripts with two new functions:

• NSOA.listview.data(listviewId) — Read the published list view data available to the user running the script. The function returns a specialized list view data iterator (length, index, next, each):

  • length — number of items

  • index — index of last returned item

  • next — returns the next item from the data iterator or undefined when the iterator is done

  • each — calls specified function for each item in the iterator

  The function consumes 10 units for each 1000-item page loaded into the iterator on-demand. It consumes 10 units for the first fetch even if empty.

• NSOA.listview.list() — Read the list of published list views available from the OpenAir OData service. Returns the list of published list views. Each item in the list has the following properties:

  • ID— The published list view OData resource ID

  • Name — The name of the list view

  • Last published — The date and time the list view was last published

    Important: The Last published property will be Last_published with an underscore instead of the space if the optional feature Replace Non-Alphanumeric Characters with Underscores in Column Titles and Metadata is enabled for your account. Accommodate both possibilities in your scripts to ensure your scripts continue work whether the feature is enabled or not.

  The function consumes 1 unit.

The data read by your scripts is exactly the same as the data you can see in your list view at any given time.

Accessing published list views using the NSOA.listview.data(listviewId) and NSOA.listview.list() user scripting functions does not use any of your allocated OData requests.

Both form and scheduled scripts support the NSOA.listview.data(listviewId) function. However, the number of items you can process in form scripts is restricted by the scripting governance time limits. The function is best suited for reading published list view data in scheduled scripts, which allow up to 1 hour of JS runtime and 1 hour of web services API call time.

Note: The OpenAir Business Intelligence Connector must be enabled for your account to use NSOA.listview and NSOA.report functions. OpenAir Business Intelligence Connector is a licensed add-on. To enable this feature, contact your OpenAir Sales Representative.

For more information about publishing list views, see the OpenAir Business Intelligence Connector Guide.

up

Business Intelligence Connector

Business Intelligence Connector Extended List View Coverage

Publish all your essential list views and access the most up to date OpenAir data from your preferred Business Intelligence (BI) tools.

You can read data from all essential OpenAir list views in real-time by publishing these list views to the OpenAir OData service.

The extended coverage includes the main list views from the Expenses, Invoices, Projects, Purchases, Resources, Timesheets and Workspaces applications. The following list views are currently supported:

• Expenses — Expense reports, Authorizations, Alerts

• Invoices — Invoices, Charges

• Projects — Bookings, Projects, Tasks, Issues, Alerts

• Purchases — Purchase requests, Purchase Orders, Fulfillment, Fulfillments

• Resources — Resources, Bookings, Alerts

• Timesheets — Timesheets, Time entries, Time off requests, Leave accrual, Alerts

• Workspaces — Workspaces, Alerts