Assisted Service Technical Information

This section describes what happens behind the scenes when you are assisting another user.

User Security

When you assist another user your security group membership does not change. Assisting does not grant access to content secured to the user being assisted, or remove access to content the agent could originally see. This is key in preventing escalation of privileges - you wouldn't want a regular user "assisting" your HR Manager and gaining access to all of the HR content on your intranet.

Workflow and History in Assistance Mode

When interacting with forms, workflow processes, and other elements that write to the history service, the details of the current user and those of the user being assisted are recorded. This is most easily seen in a history event:

"event": {
    "private": false,
    "historyDescription": "This is the event history description",
    "description": "You submitted a form",
    "proxyUserId": "TIMGADMIN",
    "formData": {
        "data": {
            "FORMACTION.FINISH": "Submit",
            "MESSAGE": "Actually filled in by timgadmin",
            "NAME": "Tim"
        },
        "formName": "FORMWITHHISTORYWRITE",
        "typeName": "FORM_FORMWITHHISTORYWRITE",
        "formDefinitionType": "FORMDEFINITIONEX"
    },
    "event": "Form Submitted",
    "userRole": null,
    "userId": "TIMG"
}

In this example the user TIMGADMIN was assisting TIMG. TIMG is recorded as the userID who submitted the form and created the event, and TIMGADMIN as the proxyUserId. Under normal circumstances, without assisted service, the proxyUserId value would be empty.

A similar method is used in the workflow worker. The assisted user's name provides the value for the initiator process variable, and should a workflow be started in assistance mode, the user who started the process on behalf of the initiator is recorded as the _initiatorProxy. Individual tasks generated during the execution of a process instance record the user and proxyUser in the _claimed, _completed and _released process variables.

Saved Forms

The Save Button in the forms designer can save a partially completed form to be completed at a later date. Any forms a user has saved are listed on the My Account template.

Assisting a user who has already saved a form and visiting the My Account template would allow a staff member to pick up and carry on with the form on behalf of the user. Similarly, if a staff member assists a user and saves a form, the user could retrieve the saved form later via My Account. 

Context Variables

When an agent starts assistance mode, the Assisted Service template will record the assisted user's ID and username in the ProxiedUserId and ProxiedUserName context variables. All assisted service enabled templates will look for these variables and, when provided, will act as if that user were the one logged in.

Any forms will be supplied the proxied user's details via the SITEUSERID/SITEUSERNAME context variables instead of the logged in user. The logged in user will be supplied via the new PROXYUSERID/PROXYUSERNAME context variables so that a record can be maintained.

Note the difference between the variables used in the template's code and the form's context variables:

Template code:

• If the logged in agent is proxying for another user then ProxiedUserId/ProxiedUserName store the proxied user's details
• The logged-in agent's credentials are always stored in the same variables
• The logged in agent retains all of the security groups/privileges they originally had and does not gain those of the user being assisted

Form context:

• If the logged-in agent is proxying for another user then PROXYUSERID/PROXYUSERNAME contain the logged-in agent's user details. If the logged-in agent is not proxying (ie acting as themselves or proxying is disabled) then these variables will be empty
• If the logged-in agent is proxying for another user then SITEUSERID/SITEUSERNAME contain the proxied user's details. If the logged-in agent is not proxying (ie acting as themselves or proxying is disabled) then these variables will contain the logged in agent's user details

Audit Log

The Assisted Service template writes an audit log using the platform's history service. The log records:

• When a user starts assisting someone
• When a user stops assisting someone
• When a user views the details of another user

This audit log is recorded automatically and is completely separate to the "interaction log". Each of the three actions writes a separate history, with relevant information written into the history's subject:

{
    "labela": "Template log",
    "labelb": "c2093957-f358-43b2-a793-2a27f14dc1e3",
    "labelc": null,
    "labeld": null,
    "labele": null,
    "id": "3c8d7198-6e2f-4014-b9d6-92d830ab06a3",
    "created": 1605528264780,
    "lastupdated": 1605528264780,
    "sealed": true,
    "subject": {
        "private": false,
        "templateName": "assistedservice",
        "articleID": 1241,
        "description": "Started assisting user TIMCITIZEN",
        "customerUserId": "TIMCITIZEN",
        "subsiteName": "chill",
        "event": "Start assist",
        "userId": "TIMG"
    }
}

Where:

• labela - always "Template log"
• labelb - a unique ID generated by the site framework
• created/lastupdated - the time of the start/stop/view action
• templateName - the name of the template that wrote the history, in this case assistedservice
• articleID - the ID of the article using the template
• description - one of "Started assisting user...", "Stopped assisting user..." or "Viewing details for user..."
• customerUserId - the username of the user who was viewed/assisted
• subsiteName - the name of the subsite the template was accessed on
• event - one of "Start assist", "Stop assist" or "View details"
• userId - the username of the person who accessed the template

URL Query String Parameters

The following query string parameters can be added to the URL of your Assisted Service article (and can be combined using ampersands as normal). This functionality is most commonly used when integrating with softphone and screen/phone pop call centre apps.

For example, if you would like to search for the incoming caller's telephone number, the URL your phone software should link to would be https://www.mywebsite.com/article/593/Assisted-Service?q=01752+123456, where 01752 123456 is the user's telephone number.

Any value from the user's profile can be passed to Assisted Service, provided that that field is marked as searchable in the underlying SITEUSERPROFILE object. If a field is added to the user profile, or an existing field changed to searchable, the site user profile object collection will need to be re-indexed.

Tidying Old Interactions

The Interaction Log is designed to record information about an Assisted Service session while a staff member is assisting a user. When someone stops assisting a user, the interaction log should be completed and closed (or passed to a colleague, who will do some more work, then close it). Interactions remaining open for longer than an assisted session don't make sense, and will distort any reporting you are doing.

There are sometimes instances where interactions are accidentally left open, running in the background potentially forever. To tidy up these logs, you can run a scheduled end point that will close open interactions older than a set number of days.

Set up an end point Scheduled Tasks to call the goss.AssistedService.closeOldInteractions end point. There are two optional parameters:

{
    "daysToRetain": 10,
    "dryRunMode": true
}

• daysToRetain - defaults to 8 if not set
• dryRunMode - defaults to false. If true, will output debug information about the interactions that would be closed