Introduction
There are times when it is useful to send a link in an email to a citizen or a back office team, to advise them that there is a task that requires their action, ie where the person updating the task is not regularly logged in and monitoring their dashboard (either Dash or Self).
Using {TaskURL} and {PublicTaskURL}
The {TaskURL} and {PublicTaskURL} tokens are to be used in email integrations that run on creation of a stage form within the process designer (ie they cannot be run on submission or escalation).
- These tokens are case sensitive and so must be used as written above. eg The url should look like this in the integration https://my.council.gov.uk{PublicTaskURL}
Please note: you do not need to add a forward slash (/) to the URL before the opening bracket ({). - Usually these are used by adding the appropriate token link to an email integration to be used to advise another officer to update a second stage, then on the second stage set the email integration to run on creation. This will then send the email with a link to the task.
{PublicTaskURL}
{PublicTaskURL} is used to open up the created stage of a process in a Self or Dash site. In the content of the email integration, the URL would follow the format of
https://yoursitename-self/dash.achieveservice.com{PublicTaskURL}
or
https://yoursitename-self/dash.achieveservice.com{PublicTaskURL_encoded}
The recipient of the email will see a link to open up the created stage of the process in the Self or Dash site.
{TaskURL}
{TaskURL} is used to open up the created stage of a process in the forms designer. In the content of the email integration, the URL would follow the format of
https://yoursitename-forms.achieveservice.com{TaskURL}
or
https://yoursitename-forms.achieveservice.com{TaskURL_encoded}
The recipient of the email will see a link to open up the created stage of the process in the Forms site.
Adding a Creation Integration
As above the {TaskURL} and {PublicTaskURL} tokens can only be used in email integrations that run on creation of a stage form, therefore to add correctly to your process they should be added to the stage that the user receiving the email will be required to action, that is unlikely to be the first stage of a process.
There are a number of occasions where is would be useful when escalating a case to a user to provide them with the {PublicTaskURL} in the email as part of the reminder that the task is outstanding and to facilitate easy access to the task, whilst {PublicTaskURL} cannot be used in an escalation integration you can achieve the same effect as follows:
- Instead of generating an escalation email, make the escalation trigger a change of stage at the reminder time, or make it trigger a loop to a new instance of the current stage if that works better for your process.
- Then you can add a creation email on the new stage and include the {PublicTaskURL} token in it.
- To further finesse you can add a field which includes the reminder date and set a condition on the creation email to only be sent if the reminder date field is populated. This ensures the creation email will not be triggered by any other route to the stage.
Authentication
No tasks are accessible unless the user is authenticated. Users must therefore be logged into the product in order to use a task url or Dashboard. This is due to information security concerns. Without authentication the product cannot determine if the user using the URL is the intended filler for the task and any task may contain sensitive or restricted information so the correct access permissions must be applied. Also, under GDPR legislation, all processing of data must be audited, which cannot be done if access is anonymous.
If you wish to ensure your user is automatically authenticated and passed directly to the task - eg back-office staff you can use the format:
https://[SERVER]/authapi/auth?provider=[PROVIDER-NAME]&uri=[URL to form]
eg. https://yourselfsite-here.achieveservice.com/authapi/auth?provider=Your_FAM_Name&uri=http://yourselfsite-here.achieveservice.com
To simplify the reuse of this string - it is possible to covert the first part of the URL into an Environment token eg {stringtoken} and then the above link can be reused in your emails in the simpler format of
{stringtoken}{PublicTaskURL_encoded}
The recipient of the email will see a link to open up the created stage of the process in the Self or Dash site.
Important Points
- The process needs to be published and the first task completed in a published environment, (Self, Dash, etc.) Filling in the first stage within the Forms Designer will not trigger the URL properly, so you cannot test using the Fill option in forms.
- If the URL the recipient receives is of the format https://yoursite.com/forms/Task/nnnnnnnnn , then the presence of forms in the URL indicates that the submission was made using the Form Designer site, not Self/Dash.
- Or, if the process involves using a Fill Task, it is likely that your Fill Task payload is missing the published flag ("published": "true").
- As with all tasks (second stages and beyond in a process), these URLs will only work when the user is authenticated.
- The category must be enabled on the site where the stage is to be updated (the process can be hidden if required but must be enabled)
- If the process is in a hidden category, then the automated login via your authentication provider will not work.
- {TaskURL} and {PublicTaskURL} can only be used in creation integrations. They will not work on submission/escalation integrations.
- If on clicking a link in a task url email the user sees the message: This task does not exist or has been closed, then the user does not have the required permissions to complete the task.
- This can happen when the user who is the originator of the task is not assigned the task, as they are not able to access it unless assigned to it.
top of page
Further useful reading:
