Maintenance required - Friday January 22nd 12pm (PT)

Support Central will be briefly offline on Friday January 22nd from 12:00 pm (PT) while we make improvements and upgrades to this site.

You are here

Recommended ways to replace the deprecated FULL search in Mail and Documents API

Friday, 21 August, 2020

As mentioned in a previous post - the FULL search_type option is being deprecated from Aconex Mail and Documents API searches - this means that any scripts or applications which are currently utilising that search mode will need to be adjusted. This post is intended to clarify what is changing and the recommended approaches to updating your scripts.

For starters - here are a few examples of the type of search which will not be possible after these changes have been made:

1) Full searches
Eg: /api/projects/{projectId}/mail?search_type=full&mail_box={mailBox}&queryParams

2) Paged searches with pageSizes > 500
Eg: /api/projects/{projectId}/mail?search_type=paged&page_size=2000&page_number=1&mail_box={mailBox}&queryParams

... and here are the recommended revised approaches

Instead of using FULL search mode to attempt to download the whole Mail or Docs register in one request, use PAGED searches that return the full set as a series of smaller paged chunks. This effectively breaks the one large request into smaller more manageable chunks and increases the overall speed at which the results are returned.
Note: For very large projects this could still represent a heavy operation so where possible please try to schedule these sort of queries outside of normal business hours.

SAMPLE REQUEST (Mail Paged Search)

/api/projects/{projectId}/mail?search_type=paged&page_size=250&page_number=1&mail_box={mailBox}&queryParams

SAMPLE RESPONSE
note: for brevity’s sake, this example query returns only MailID and MailNo. In a real world example any/all metadata from the individual mails could also be requested/returned.

<?xml version="1.0"?>
<MailSearch TotalResultsOnPage="50" TotalResults="255" TotalPages="6" PageSize="50" CurrentPage="1">
<SearchResults>
<Mail MailId="106">
<MailNo>CAN-000002</MailNo>
</Mail>
<Mail MailId="29">
<MailNo>CAN-000001</MailNo>
</Mail>
<Mail MailId="1053">
<MailNo>CA-000001</MailNo>
</Mail>
....
</SearchResults>
</MailSearch>

Repeat this request (looping through the total number of pages until all the desired results are retrieved.

SAMPLE REQUEST
# seed the loop variables from the initial PAGED search request
pageNumber = CurrentPage
totalPages = TotalPages

for(pageNumber in totalPages)
{
/api/projects/{projectId}/mail?search_type=paged&page_size=250&page_number={pageNumber}&mail_box={mailBox}&queryParams
#add the results to the locally stored total result set
}

-----------

UPDATING THE RESULTS OVER TIME

If the purpose of this API request is to keep a full ongoing record of mail/docs data, the most efficient method is to use the Integrity API.
This allows you to retrieve only those records which have changed or been added since the last update.

HOW TO USE THE INTEGRITY API
1 - when making your initial request to retrieve the current set of records, record the timestamp of that initial request.
2 - Use that timestamp and /integrity API to retrieve only the data with the records which have changed since the last request

SAMPLE QUERY
#Use the stored timeStamp (e.g like 2020-04-11 00:00:000Z)
/api/projects/{projectid}/mail/integrity?mail_box={mailBox}&everythingsince={timeStamp}

SAMPLE RESPONSE
The integrity api result would look something like:

<IntegrityCheckResults TotalResults="5">
<Mail lastModifiedDate="2020-04-03 00:32:02.472Z" id="1879052875">
<Mail lastModifiedDate="2020-04-03 01:25:04.712Z" id="1879052876">
<Mail lastModifiedDate="2020-04-03 02:32:02.231Z" id="1879052877">
<Mail lastModifiedDate="2020-04-03 06:57:14.421Z" id="1879052878">
<Mail lastModifiedDate="2020-04-03 09:30:02.721Z" id="1879052879">
</IntegrityCheckResults>

Use the correspondence ids from the integrity results and make an api call to dedicated endpoint we have for individual correspondence retrieval and get the correspondence details for each of those ids

for(correspondenceId in integritySearchResults)
{
/api/projects/{projectId}/mail/{correspondenceId}?queryParams
}