Refreshing Accounts

For efficiency, HQ and UUX cache a user’s accounts for the duration of a session. This means from the moment your end user logs in until they log out, their account list will not change. Most of the time, this leads to a snappier front end experience, since calculating accounts is an expensive operation, often involving real time calls to the Core. However, if your workflow involves updating or linking an account, this is a hindrance. Fortunately, the SDK provides a way of refreshing these accounts outside of the normal login flow.

Warning

This only applies to workflows where the end user logs into the Online environment

The accounts are cached in both UUX and HQ. So you need to clear the cache in HQ and UUX for account changes to show up. Let’s first cover the HQ cache clearing using HqCommands.

class q2_sdk.hq.models.hq_commands.HqCommands(reload_type, accounts_to_reload, force_success_response=False, disclaimer_id_to_skip=None)[source]

For use with sending special instructions to HQ via an execute_request_as_xml response

Parameters:

  • reload_type (AccountReloadType) – Reload from either Q2’s database or the Host Adapter

  • accounts_to_reload (list) – List of account numbers (host account ids HAIDs). If blank, will reload ALL accounts (This can be expensive and is not recommended)

  • force_success_response – Must be set to True to allow Disclaimers to move on with their flow

  • disclaimer_id_to_skip (Optional[int]) – Q2_DisclaimerFormData.DisclaimerFormDataID. If set, will mark the disclaimer viewed for the duration of the online session

To understand the use of this method, let’s review a typical SDK workflow:

Q2Online -> HQ -> SDK -> HQ -> Q2Online

  1. The end user does something in the online environment. Perhaps clicking on a submit button in your SDK form.

  2. This tells HQ to find the registered SDK extension. HQ then POSTs to your extension with a blob of XML including the user’s information, such as their email, SSN, Account List, etc.

  3. It is the responsibility of your extension to generate some HTML to return back to HQ, which the SDK framework wraps in an appropriate SOAP response before returning.

Step 3 returns something like this:

<FormRsp xmlns="http://tempuri.org/FormRsp.xsd">
<FormResp>
    <TargetUrl/>
    <PrependVirtualDirToUrl>false</PrependVirtualDirToUrl>
    <MessageToEndUser/>
    <NewFormData>{form_data}</NewFormData>
    <NewFormShortName/>
    {hq_commands_xml}
</FormResp>
</FormRsp>

{form_data} is substituted with whatever you return from your extension. Meanwhile, {hq_commands_xml} can give HQ special instructions. This is the hook that allows us to refresh the accounts during an active session.

In practice it looks something like this:

from q2_sdk.hq.models.hq_commands import HqCommands
...

async def submit(self):
    ...
    html = self.generate_html()  # Imagine this does some magic to generate your form
    accounts_to_refresh = []
    for acct in self.account_list:
        accounts_to_refresh.append(acct.host_acct_id)

    self.set_hq_commands(
        HqCommands(
            HqCommands.AccountReloadType.FROM_HOST,  # Host means Core in this case
            accounts_to_refresh
        )
    )
    return html

You are returning your HTML as you normally would, but calling self.set_hq_commands will inject an appropriately formatted {hq_commands_xml} string into Step 3 above.

Note

The accounts are not refreshed until the method is returned. A common gotcha is try to act on the refreshed account list during the same call in which self.hq_commands is set. Until that call is returned, HQ has not been given the instruction to refresh the accounts from the core.

Next, you need to execute Tecton’s notifyRefetchAccounts API function in the browser. You will not see and updates of the accounts in UUX until this function is run.