Content
What is Aconex?
ACONEX is a cloud-based project management platform designed to facilitate collaboration and streamline the management of construction, engineering, and architectural projects. It connects teams and processes across the entire project lifecycle, capturing a complete project record with an unalterable audit trail to minimize disputes. Founded in 2000, ACONEX stands for Australian Construction Exchange, reflecting its origins in the construction industry.
ACONEX (at the time of writing this article) is owned by the software company Oracle, which also own Primavera P6 scheduling software.
What is O3 Integration?
O3 Integration is our toolset to integrate information / files / documents / drawings / models etc. from a data repository, such as Autodesk's BIM 360 / ACC, Microsoft SharePoint, and Aconex. Further integrations may be added to support other platforms in future where a requirement exists.
This article will focus on 'Aconex'
If interested in SharePoint and/or BIM360/ACC integration configuration, please visit This Link.
Getting Started - Connection
O3 connects to Aconex as a background integration. Nobody signs in to Aconex when a sync runs, so Aconex has to be told in advance that O3 is allowed to act on your behalf. That happens once, on your Aconex tenant, and produces the credentials you then enter in O3.
Before you start
Registering the application requires Lobby Admin rights on your Oracle Smart Construction Platform account. If you do not have them, your Aconex account administrator will need to complete the first part of this section for you.
Project Setup - Integrations
First we need to establish a new integration. To do this you will need to be an admin or have the correct permissions to edit this area.
Open Project Set-up, Project Settings, Integrations and click on '+' button in top right.
When presented with the 'Add Integration' form, select the Integration type as 'Aconex'. Provide a description of your choosing and then click on 'Save' button.
After Save, O3 will open the Integration form layout, which is also used for future editing of the connection as required. To establish a connection, click on the Connection tab (shown by default).
Register O3 as an OAuth client in Aconex
Sign in to the Oracle Smart Construction Platform Lobby at
https://constructionandengineering.oraclecloud.com/web/home.Choose OAuth Clients from the main menu, then click Add.
Complete the form:
Field | What to enter |
Name | Something identifiable, such as |
Description | For example, Connects O3 Solutions to Aconex for document, drawing, package and model sync. |
Resource Application | Aconex APIs — the default. |
Integration Type | User-Bound Integration. See the note below. |
User Account | The Aconex account the integration will act as. See Choosing the bound user below. |
Organizations | The organisation or organisations that contain the project you intend to sync. |
Terms of Use | Accept. |
Click Add. Your new client appears in the list. Click the eye icon to reveal the Client Secret.
Why User-Bound Integration
Aconex offers four integration types. O3 runs unattended on a schedule, with no user present to complete a browser sign-in, and authenticates with only a Client ID and Client Secret — which is exactly what a User-Bound Integration provides. Web Server Application and Installed Application both require a redirect URL and an interactive sign-in, so neither will work with O3.
Choosing the bound user
Every Aconex API call O3 makes runs as this user and sees exactly what that user can see. Use a dedicated integration account rather than a real person's, so your syncs do not break when someone changes role or leaves the project.
On each project you intend to sync, that account needs:
permission to search the document register and download documents;
access to any confidential documents you expect to sync — Aconex withholds confidential documents from users who are not on the document's access list, even when they can otherwise search the register;
access to packages and models, if you plan to enable Sync Packages, Sync Associations or Download Models from Aconex Packages API.
If your tenant uses SSO or 2-Step Verification
When your identity domain enforces SSO or 2SV, the new integration has to be allowed explicitly or Aconex will refuse to issue a token:
Add the integration to the IdP Policy under Security › IdP Policies › Apps.
Add the integration to the Sign-on policy under Security › MFA › Sign-on policies.
Skipping this produces an invalid_amr_claims error when you test the connection in O3.
Where each connection value comes from
Enter your Aconex connection information on the Connection tab. Every value comes from one of two places: the OAuth client you registered in the Lobby, or your Aconex project itself.
O3 field | Value | Where to find it |
Aconex Auth URL |
| Always this value — it is the Lobby that issues the access token, not something specific to your project. Use |
Aconex Data URL |
| The regional Aconex instance hosting your project — the same host you see in your browser's address bar when signed in to Aconex. Replace |
Client ID | Issued with the registered application | Lobby › OAuth Clients › select your client. |
Client Secret | Issued with the registered application | Lobby › OAuth Clients › select your client › eye icon. Lobby Admins can view this again later. |
Aconex Project ID | A number | In Aconex, open the project. From the Tasks page click Project Details at top right, or the project logo beneath it. The Project ID is near the top of the page. |
Aconex User ID | A number | In Aconex, go to Setup › User › Account Details. The User ID appears just above Title. It must belong to the user the application is bound to — not whoever is doing this configuration. Organisation Admins can look this up for any user from the User Accounts List. |
Aconex User Site |
| The Aconex instance URL for that user, which in practice is the same value as Aconex Data URL above. This is a URL, not an ID number. |
The Aconex panel on the Connection tab with all fields populated and the Test Connection button.
Two things that catch people out
Aconex User Site is a URL. It is not an organisation ID, a site number, or the Project ID. If you are looking for a number, you are looking for the wrong thing.
Leave the trailing slash off both URLs. Enter
https://constructionandengineering.oraclecloud.com, not…oraclecloud.com/.
Copy every value exactly as shown. They are case sensitive and must not carry leading or trailing spaces. The Client Secret is write-only: once saved it displays as ********, and leaving it masked when you next edit the integration keeps the stored value. You only need to re-enter it if the secret itself changes.
When supplied click on the Test Connection button to make sure the supplied credentials work. O3 saves any pending changes first, then confirms whether Aconex accepted them.
Do you need Aconex User ID and User Site?
These two fields exist because a single Lobby account can be linked to more than one Aconex account. When that is the case, Aconex will not guess which account to act as, and the connection is refused until you say.
Is the bound Lobby account linked to more than one Aconex account?
Yes - Both fields are required. Supply the bound user's Aconex User ID and their instance URL.
No - Leave both blank. Client ID and Client Secret are enough.
Not sure - Leave both blank and click Test Connection. If Aconex responds with invalid_aconex_account, fill both fields in and test again.
Both or neither
Aconex rejects a request carrying only one of these values. O3 will let you save the integration with just one filled in, so check both before testing.
Additional Connection Settings
Further down the Connection tab you can also add additional connection settings. These are optional and depend on your required configuration.
For ignored file extensions, for example, you could enter something similar to what is shown below if applicable:
.docx,.xlsx
Note you will need to include the '.' period in front of the file extension being ignored and separate multiple file extensions to ignore with a ',' comma.
If you 'Sync Packages' turned on you will likely need to put in a 'Package Filter' such as to identify a keyword like 'XX-IWP' 'FIWP' or 'IWP' to identify your IWP package coded documents.
Aconex Field Mappings can also be set-up. As with the above settings, theses settings are not always required, but present where needed.
To add, click on 'Add Item' button. Provide a name for the Field Mapping rule. Then click on the right pointing triangle button to expand.
Build you rule steps and apply filters as applicable.
You can use the Value Builder syntax.
See the Field Mapping section below for more information.
Please note, this configuration can be complex and further support can be provided by the O3 Solutions Team upon request.
Troubleshooting the Connection
These errors come from Aconex rather than from O3. O3 passes the response through unchanged, so a failed test looks like this:
Connection Failed. The following error was encountered while connecting to the host: Failed to obtain token. Status: 400, Response: {"error":"invalid_aconex_account","error_description":"Aconex account not specified"}
Match the error value from that response against the table below.
Error | What it means | What to do |
| The bound Lobby account is linked to more than one Aconex account. | Fill in Aconex User ID and Aconex User Site, then test again. |
| The account you specified is not linked to the bound Lobby account. | Check the User ID belongs to the bound user, and that User Site is that user's instance URL. |
| The bound Lobby account has no linked Aconex account at all. | Ask your Lobby Admin to link the account, or to bind the application to a different user. |
| The application is not permitted to act as the requested account. | Check the application's Organizations include that account's organisation. |
| Client authentication failed — wrong Client ID or Secret, or stray whitespace. | Re-copy both from Lobby › OAuth Clients. |
| A value is malformed — most often | Confirm Aconex User Site is a full instance URL such as |
| Your identity domain enforces SSO or 2SV and this integration has not been allowed. | Add it to the IdP Policy and Sign-on policy, as described under Register O3 as an OAuth client. |
If the failure is on the Aconex side — a missing linked account, or a User ID you cannot locate — your Aconex account administrator or Aconex support can retrieve the values tied to a registered Client ID.
The connection succeeds but the sync returns nothing
Test Connection confirms only that Aconex issued an access token. It does not check that the bound user can see your project's data, and it does not validate the Project ID. If the test passes but a sync brings back nothing or errors, check each of these:
The Aconex Project ID is the project you actually meant.
The Aconex Data URL points at the region that hosts that project. A valid token will not help if O3 asks the wrong regional instance for it.
The bound user has access to the project, and permission to search the document register and download documents.
If Sync Packages, Sync Associations or Download Models are on, the bound user can also see packages and models on that project. Sync Packages is a prerequisite for both of the others.
Documents are not confidential ones the bound user is excluded from — Aconex will not return those, and they will simply be absent rather than reported as an error.
Test the first run small
Turning on Test Mode limits a sync to the first 20 matched records, so you can confirm documents arrive and land where you expect before committing to a full project sync.
If you added Additional Aconex Document Fields
Any field name Aconex does not recognise for your project is skipped and reported as an import warning. Rather than typing names by hand, use the Choose Custom Fields button, which reads the valid field identifiers from your project — save the connection first, since it uses the saved credentials.
Getting Started - Syncing
The Sync facility ensures when O3 syncs with Aconex. You will need to select your API User (this user account should have the necessary permissions to update O3, typically set as a system admin). A schedule is selected, keeping time zone and what time to run the sync in mind.
Typical examples are going to be daily syncs, which can be run outside normal business hours, allowing for time to complete the syncs before the workforce are using O3 and not inhibiting normal performance. You should also consider any external sync schedules with Aconex to ensure you have the latest information!
Getting Started - Integrate Drawings, Documents, RFIs, Schedules and Models
Lastly, on the configuration side, decide what you want to bring in from Aconex. This can be Drawings, Documents, RFIs, Vendor Data, Schedules, 3D Models, Non-Graphical Imports and Pipe Data, or any combination of these. Each type has its own tab on the integration, after the Connection and Sync tabs.
Drawings, Documents, RFIs and Vendor Data are set up the same way. Each tab has two settings:
Filters: the conditions a Document Register record must meet to be imported as that type.
Data Deliverable: the deliverable whose field mappings are used to import the matched records. The setting is called Drawing Data Deliverable, Document Data Deliverable, RFI Data Deliverable or Vendor Document Data Deliverable, depending on the tab.
Schedules, 3D Models, Non-Graphical Imports and Pipe Data use a list of items instead. Each item has its own filter and a setting specific to that type: the schedule to update, the model parser configuration, the import type, or the pipe data translation type.
Drawings, Documents and Vendor Data download the file attached to each matched record. RFIs are imported from the record's details only, and the attached file is not downloaded.
Every tab you use needs a filter. A tab with no filter imports nothing, even if the register holds records of that type. Read the next section before you write your filters.
How the Sync Sorts Records into Types
Every type the integration imports comes from the same place: your project's Aconex Document Register. On each sync, O3 downloads the register once and applies any Aconex Field Mappings from the Connection tab. It then checks each record against the filter on every tab. Three rules follow from this.
1. A tab with no filter imports nothing
An empty filter does not mean "import everything". If the RFIs tab has no filter, no RFIs are imported, however many RFIs the register contains.
2. A record can be imported as more than one type
The Drawings, Documents, RFIs and Vendor Data filters are checked independently of each other. A record that matches two of them is imported into both. For example, if the Drawings and Documents tabs both use the filter Filename Ends With pdf, every PDF in the register is imported twice, once as a drawing and once as a document.
On the Schedules, 3D Models, Non-Graphical Imports and Pipe Data tabs, only the first matching item in each tab's list is used, so the order of the list matters. A record can still be picked up by several different tabs.
3. A record that matches no filter is skipped
The import log shows a warning for each one: Skipping item <filename> because it did not match any rules. If you see many of these, a tab's filter is narrower than you intended, or a type you need has no filter yet.
Writing filters that don't overlap
Base each tab's filter on a field that tells the types apart, usually DocumentType, and avoid conditions that several types share, such as a file extension. Each record should match exactly one of the Drawings, Documents, RFIs and Vendor Data filters.
Tab | Example filter |
Drawings |
|
Documents |
|
RFIs |
|
Vendor Data |
|
These values are examples. Document types differ from project to project, so take the real values from your own register. Every sync attaches the raw data it downloaded to its import record, listed on the Import History tab, and the Documents worksheet in that file lists each record's DocumentType.
If the type can only be worked out from a pattern, such as part of the DocumentNumber, use an Aconex Field Mapping on the Connection tab to derive it first. Filters see the mapped value. See Different Field Mappings below.
Aconex Mail is not supported
The integration reads the Document Register, plus Packages when Sync Packages is on. It does not read Aconex Mail. RFIs that exist in Aconex only as Mail items are never seen by the sync and cannot be filtered or imported. For RFIs to come across, they must be registered as documents in the Document Register with a document type your RFIs filter can match. Check with your Aconex administrator how RFIs are recorded on your project.
Quick checks
What you see | Likely cause |
No RFIs arrive | The RFIs tab has no filter, the filter doesn't match the register's DocumentType for RFIs, or the RFIs exist only as Aconex Mail. |
The same file appears as a drawing and a document | The Drawings and Documents filters overlap. Tighten one or both so each record matches only one tab. |
Many "did not match any rules" warnings | No tab's filter matches those records. Add or widen a filter, or add the extension to Ignored File Extensions if you never want them. |
Data Deliverables
For more on Data Deliverables, click here.
You can use Data Deliverables to set-up scheduled imports with your Aconex Integration.
Click on Data Management - Data Deliverable grid. Click on '+' button and then input your initial Data Deliverable attributes. You will want to set the 'Import Type' to what you are trying to import into O3, such as Documents.
You can set up the Data Deliverable as automatic and schedule the frequency for how often it imports.
However, to connect the Data Deliverable to your Aconex Integration, this needs to be done from the Integration itself and not from the Data Deliverable form. Otherwise, you will see an error such as what is shown below!
So return to the integration configuration, and switch to e.g. Documents. Then set the Data Deliverable that will import your e.g. Documents.
If we save the integration configuration, and return to our example document import Data Deliverable, we can now see the connection under the Integrations tab.
Similarly, this can be set-up with Drawings for example (note a separate Drawing based Data Deliverable would need to be set-up).
Each of the Drawings, Documents, RFIs and Vendor Data tabs needs its own Data Deliverable, with an Import Type that matches the tab: Drawings, Documents, RFIs or Vendor Data. The Data Deliverable dropdown on each tab lists every Data Deliverable on the project, whatever its Import Type, so check you pick the one set up for that tab.
See the Field Mapping section below for more information.
Package Syncing
Package syncing on an integration is a manual trigger that updates data between O3 and external systems like Aconex.
You can sync from the Data Deliverable Details form, under the Integrations tab, using the 'Sync' button, or from Project Settings - Integrations. This triggers a manual sync for the folder associated with the deliverable.
On the Project Settings - Integration - Connection tab under Settings, you can also apply Package Syncing and add in a filter.
Associations Entity Type
You can specify entity types when syncing associations from Aconex.
This adds additional columns to the generated associations CSV file, allowing the import process to properly categorize both sides of the association.
This is useful if you have the same nomenclature reference on different entities like say a drawing and an engineering package (EWP)!
How to Configure The Association Type:
Navigate to Project Setup > Project Settings > Integrations
Select your Aconex integration
In the Aconex settings section, locate the two fields near "Package Filter":
- Associations Source Entity Type
The entity type for the source/left side of the association (e.g., "IWP", "CWP")
- Associations Target Entity Type
The entity type for the target/right side of the association (e.g., "Drawing",
"Document")Save your integration settings
Association Example:
If you set for example:
Associations Source Entity Type = CWP
Associations Target Entity Type = Drawing
The generated CSV will look like:
Entity Name,Entity Type,Associated Entity Name,Associated Entity Type
PKG-001,CWP,DWG-001,Drawing
PKG-002,CWP,DWG-002,Drawing
Notes
These fields are optional. If left blank, the system uses the existing 2-column format (i.e. just the names and not the types) for backwards compatibility.
The values you enter are applied to all associations in the sync - they are not determined per-row.
Field Mapping
Another point for consideration is field mapping. Chances are the fields in your source files / documents do not line up with the O3 fields you want to populate. This is quite common, but O3 provides a facility to match common fields with different naming used in in Aconex.
See on the Project Settings - Integration - Connection tab - under Aconex Field Mappings.
Different Field Mappings
What are differences between Field Mappings?
The field mappings on the Connection tab are pre-mappings that get applied before the data from Aconex is sorted into Entity Types. The use case built was where a certain pattern in the DocumentNumber indicated whether or not the record was a document or drawing (i.e. the data after the third dash was numeric for documents, and alpha for drawings). Once those mappings have been processed, the record is sorted according to the filters on the Drawings, Documents, RFIs and Vendor Data tabs (and the other type tabs), and then the field mappings on each tab's Data Deliverable apply.
Summary Points and API Considerations
The Aconex integration configuration is similar to the BIM 360 integration, allowing for multiple integrations with different schedules.
Configuration requires Aconex client ID, secret, project ID, user ID, and site.
Options include syncing packages and associations or only documents.
The
Sync Packagesoption is a prerequisite forSync AssociationsandDownload Models.Most projects will likely enable both
Sync PackagesandSync Associations.
Custom fields for packages and associations can be configured.
The integration can ignore specific file extensions (e.g., TXT files) to prevent errors.
Data is pulled from Aconex using the Documents API by default, and the Models API if packages are synced.
Raw data imports are available in a spreadsheet with three tabs: Documents API, Packages, and Relationships.
Pre-mapping is applied to the data upon ingestion, before any filters are applied, to manipulate attributes like document type based on conditions.
Sync schedules are configured with an API user (recommended to be named for the integration, e.g., "Aconex Integration") and a frequency (e.g., daily, weekly).
Drawings, Documents, RFIs and Vendor Data are all sorted out of the same Document Register using each tab's filter, usually based on document type. A tab with no filter imports nothing.
Keep filters from overlapping. A record that matches more than one tab's filter is imported as each of those types.
Aconex Mail is not read. RFIs that exist only as Mail items are not imported.
Further Support
We understand configuration settings can be complex and difficult to set-up. Please reach out to O3 Support at Support@O3.solutions, the in-app support (bottom right of screen) or speak to your O3 Project Manager if assigned, if you need help.















