Salesforce – Understanding the ‘ids’ System Variable

apexlightning-web-componentslistscreen-flowvisual-workflow

I am recently working on a project to pass selected records from a list view to a screen flow. I pretty much have it working, but there is one aspect I am using that I really don't understand, and I would love to learn more about it. In this process, I found a blog post that suggests accepting the selected records IDs in the screen flow by creating a variable with the api name listed EXACTLY as ids – no case differences. I have found several unofficial and old sources talking about this 'ids' variable, mostly how important it is to match the casing. One unofficial source described ids as a system variable. All the few places I have seen reference to this 'variable' only say that it 'must match this (ids) value to work' with no additional explanation.

However, I have been unable to find any substantial documentation about this ids variable, official or otherwise. I am looking for a detailed explanation as to what exactly this ids variable is, how it works, the appropriate context in which to use it (just flows, or possibly also in Apex code, LWC, etc), and if there are any other variables of this type (for example, passing a list of entire records to a flow from a list rather than just a list of ids).

Just for context, I have been trying to figure out how to implement this using a variety of technologies, including screen flows, Lightning Web Components, and also custom apex. So far, I have only found that the ids variable applies to the screen flow.

Does anyone have any experience or knowledge about this ids variable, either how it works or even what exactly it is called? I would also love help finding some documentation on this! Thanks so much.

(For context, here is the blog post I referred to: https://codingwiththeforce.com/salesforce-development-tutorial-lwc-how-to-use-lightning-web-components-in-list-view-buttons/)

Best Answer

This is actually pretty easy to follow, once you find out how it works. Basically, this is just normal HTTP standards working in unison.

To start off, when you submit a form, it creates an HTTP request that looks like this:

POST /myurl HTTP/1.1
Host: thedomain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <<size of body>>
<<other headers here>>

name1=value1&name2=value2&name3=value3&andSoOn=andSoOn

Now, more specifically, the related list buttons are actually just a normal HTML form, and will generate this same type of content. Each checkbox will submit their value, which is the Salesforce Id for that row's record, with the parameter for each selection having the key ids and the value of the record Id, such as:

ids=id1&ids=id2&ids=id3

ids is the name of the form's input name that was used to pass selected records to a server where they would be processed by whatever software they had running. This could be a Visualforce page, an S-Control, or even a completely different website entirely. For example, you could use this mechanism to export selected records to an external system by giving that system the {!$Api.Session_ID} as a parameter, and the ids query string would direct the system for which records to retrieve.

You can imagine that a related list's basic markup has these fragments in it:

<form action="/buttonurl" method="post">
<table>
<tr><td><input name="ids" type="checkbox" value="record-id-1" /></td>...</tr>
<tr><td><input name="ids" type="checkbox" value="record-id-2" /></td>...</tr>
<tr><td><input name="ids" type="checkbox" value="record-id-3" /></td>...</tr>
...
</table>
</form>

It just so happens that flows use the same mechanism to read their input values. As you've undoubtedly noticed, you can pass variables into a flow. This is described in Customize a Flow URL to Set Variable Values. If you have the URL of the flow, and you know the variable names, you can pass them in either using a POST, as demonstrated above, or by query string directly.

The example in the docs shows:

/flow/MyFlow?varNumber=100&varString=Hello

The important thing to remember is that, as far as web technology is concerned, the query string (?queryString) and application/x-www-formurlencoded parameters can both be read by the server, and are often treated identically. Most features in Salesforce that uses form-style syntax support both the query string and URL-encoded body. I don't know of any exceptions, but I'm not familiar with every Salesforce technology, so exceptions may exist.

Keep in mind that the case sensitivity comes from the fact that query string parameters are case-sensitive in Salesforce. id is treated differently than Id. Similarly, that's the reason why it must be ids in the Flow variable, because the input parameters are case sensitive, and Salesforce uses ids. ids isn't an acronym, it's literally just "ids." the plural of "id."

So, once you get the mechanics, there's really nothing magical going on. You created a collection variable called ids, and Flows accept form data as described in the documentation above, and Related List Buttons happen to provide that kind of data. I don't know why they decided not to put it in the documentation, although I guess it makes sense, given that the documentation is about Salesforce, and not HTML/HTTP.

Related Topic