Documentation for retrieving a Document is in error

[tfuda]

I tried following the example here: https://github.com/ejholmes/restforce#documents to download the body of a Document and save it to a file. This didn't work for me. Examination of document.Body shows that it contains a URL, like this: /services/data/v35.0/sobjects/Document/0155C00000053lWQAQ/Body for retrieving the body. To correctly retrieve the document body you must do the following:

document = client.query("SELECT Id, Name, Body FROM Document WHERE FolderId = '#{folder.Id}').first
# Get the resource at the URL returned as "Body". This returns a Faraday::Response object
resp = ptech_client.get(document.Body)
File.open(document.Name, 'wb') { |f| f.write(resp.body) }

[timrogers]

This doesn't seem to match up with what is mentioned in the Salesforce docs - see https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_document.htm. The docs seem to suggest that documents can point to a URL or encoded data. What happens if you select Url in the query and look at that?

[daveespo]

This appears to be a bug (or, I'm sure they'll call it 'working as designed') in the Salesforce REST API

If you run a SOQL query through the API like:

SELECT Id,Name,Body FROM Document LIMIT 2002

(the LIMIT 2002 ensures that you get a nextRecordsUrl)

The first 'page' worth of records just has the URL to the Document Body field

But when you retrieve the 'nextRecordsUrl' for that same query, you see that only a single record is returned and it contains the actual binary content of the Body field

And notice that the 'nextRecordsUrl' is for offset 2001, not 4000 as you'd expect for a normal query result

This behavior of only returning the Body content if a single record is retrieved is hinted at here:

https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_attachment.htm

You can access all of the fields using a query() call. However, you can't receive the Body field for multiple records in a single query() call. If your query returns the Body field, your client application must ensure that only one row with one Attachment is returned; otherwise, an error occurs. A more effective approach is to return IDs (but not Attachment records in the Body field) from a query() call and then pass them into retrieve() calls that return the Body field.

The bug seems to be that we should've gotten "an error" by getting more than a single record back in the SOQL query .. instead, we get this bizarro behavior where it returns 2000 records in the first chunk, then only a single record for each page thereafter

Can you update the README to reflect this silliness? Because the Restforce::Collection masks the intricacies of the paginated results, you're left totally lost as to what's happening. You can probably just link to this bug report.

[timrogers]

@daveespo Makes sense! Fancy making a PR for that readme tweak? 😄