Placeholder

Customer Forum

Setting up the Case Portal

Alix (Workbooks Online) Posted: 2017-09-15 15:00

Workbooks includes a basic template for a Case Portal within the script library which is included within a paid subscription of the service. The portal configured to suit your business needs and can be a very effective tool for case management between you and your customers. You can create People records in Workbooks to invite key contacts and give them the ability to raise new Cases, update existing Cases with new information and see historic Cases. Additionally, you can make more information available to your customers in a Custom Tab (see below). For instance, you could display Open/Closed Cases plus make manuals available to clients for products they have purchased.

case_portal.png

There are quite a few steps to set up the Case Portal, which are set out below. Please ensure that you follow them closely. You will need System Administrator access to your database to follow these steps. We'd recommend that you reserve around 1-2 hours to complete this configuration. This will allow you time to:

  • Configure your email settings to send out emails from Workbooks
  • Run the plugin, configuring for your business needs as you complete each step
  • Setup a Case Portal test user
  • Test the Case Portal configuration to ensure everything is working as intended

Please contact our Support Team if you require any help.


Install the Plugin

Click Start > Configuration > Automation > Plugins > Add Plugin. Select "Script Library", and then choose "Case Portal" from the list. Click Install to being the installation.

plugin_1.png

You'll be taken through a total of 11 steps to complete the installation as follows:

1) Introduction Screen 

Simply click "Continue" on this screen to start the installation. NOTE: You must complete them all at the same time, otherwise you will need to go through the full installation again.

2) Create Picklists and Picklist Values

The Case Portal requires a number of Picklists and Picklist values to function. Mostly, the plugin adds values to already existing System Picklists. This screen shows what will be created in your database and it's current status.

plugin_picklists.png

Simply click "Continue" here and the plugin will create the missing configuration.

3) Create Custom Fields in Workbooks

The plugin needs to create the following Custom Fields. Click "Continue" to allow the plugin to automatically create these for you - If a field already exists of that name then the plugin will not create it again. A list of fields created by this plugin can be found at the bottom of this forum post, see Manual Steps below, where we'd recommend that you configure your Form Layouts to make these fields accessible to your users. 

4) Configure the Case Portal - Raise a new Case screen

This step of the plugin allows you to configure which fields appear in the Case Portal when a user clicks "Raise New Case" from the Navigation Bar.

Fields will appear in the Case Portal in the order that they are added here. If you create them in the wrong order, delete the row and re-add it before clicking "Continue". By default, if you decide to not add anything on this screen. The Raise New Case screen within the Portal, will show fields for Summary and Description as these are the minimum system required fields in Workbooks to create a Case.

Click "Add New" to begin. In the dialog box, you'll see the following options:

plugin_fields.png

  • Portal Field Name: This is the field label that will appear for the field on the Portal
  • Portal Field Type: This is the data type of the field within the Portal - the Portal currently supports Text, Picklists (populated with a Workbooks Picklist or via API Data) and Dependant Picklists. It should match the data type in Workbooks. For instance, do not provide a text field in the Portal for a field that is a picklist in Workbooks as the Case creation would fail if the user doesn't enter a valid picklist value.
  • Icon: Each field in the Case Portal can have an icon beside it. We've provided a handful out of the box, but if you know about Font Awesome, then you can override these values later in API Data.
  • Workbooks Field Name: This is a list of the available fields in Workbooks on a Case record. When a user provides a value in this Portal field and clicks "Create Case", the value provided will be mapped to the chosen Case Field.
  • Required?: Decide whether this field in the Case Portal is required before the user can submit a new Case. If the field is required in Workbooks, then you should configure it to be required on the portal too.
  • Picklist Type: If you select "Picklist" in the "Portal Field Type" dropdown, you need to set this option to either "Picklist" or "API Data" depending on how you have configured Workbooks.
  • Picklist: If you select "Picklist" in the "Picklist Type" above, this shows a list of Picklists available in Workbooks. Select the relevant one that will drive the values available in the Portal
  • API Data Key: If you select "API Data" in the "Picklist Type" above, this shows a list of unique API Data Keys. The list is driven from the Key field on an API data record. Therefore, if you are using API to drive dynamic picklists in Workbooks you should not store actual values in the Key
    • Example: Product Category stored in API Data.
      • For each Product Category, create an API Data record setting Key to "Product Category".
      • Set Key2 to the category value e.g. Subscription, Service etc.
      • You can then built a report on this data with a criteria set to only show values where Key = Product Category and the display column is Key2 to control picklist values.

Dependant Picklists (Dependant Picklist Source & Dependant Picklist Target):

The Case Portal can also support dependant picklists. These require a little more thinking about than normal fields as you need to configure Workbooks Cases with the constrained Custom Fields first - see here for further information on this. Let's take an example of Car Manufacturers and their corresponding models to illustrate how to configure the Portal. Assume, we are car rental company and we want to set up a scenario where if we select Ford in the first picklist (Dependant Picklist Source), we want the second picklist (Dependant Picklist Target) to show us all car models, made by Ford. To do this in portal, you need to create two fields

  • Car Manufacturer (1st picklist - Dependant Picklist Source)
    • Portal Field Name: Set this to be Car Manufacturer
    • Portal Field Type: Set this to be Dependant Picklist Source
    • Picklist Type: Set this to either API Data or Picklist depending on what drives the values in this field within Workbooks. You can check this under Configuration > Customisation > Record Types > Cases > Fields.
    • Icon: Choose an appropriate icon in the list
    • Workbooks Field Name: Choose the Workbooks Case field that this value will map to. You should have already configured a Car Manufacturer field on Cases, thus select this as the Workbooks field name value.
    • Required?: Decide whether this field in the Case Portal is required before the user can submit a new Case. If the field is required in Workbooks, then you should configure it to be required on the portal too.
    • Data Target: When you select a value in this picklist, the dependant values will be retrieved from the Workbooks configuration and populated into this picklist within the Portal. Therefore, in this example, we should select Car Model. Again, you should have already configured this as a field in Workbooks, otherwise it will not be available in the list to set as a Target field.
  • Car Model (2nd picklist - Dependant Picklist Target)
    • Portal Field Name: Set this to be Car Model
    • Portal Field Type: Set this to be Dependant Picklist Target
    • Picklist Type: Set this to either API Data or Picklist depending on what drives the values in this field within Workbooks. You can check this under Configuration > Customisation > Record Types > Cases > Fields.
    • Icon: Choose an appropriate icon in the list
    • Workbooks Field Name: Choose the Workbooks Case field that this value will map to. You should have already configured a Car Manufacturer field on Cases, thus select this as the Workbooks field name value.
    • Required?: Decide whether this field in the Case Portal is required before the user can submit a new Case. If the field is required in Workbooks, then you should configure it to be required on the portal too.
    • Parent Field Label: This displays as a holding message in the field until you have selected a source. The text will read "Please select a value in {parent_field_label}

In the portal, when you select a value in the Dependant Picklist Source field, values that match the selected option are retrieved from Workbooks and updated in the Dependant Picklist Target field on-the-fly.

NOTE: Not all options are available for all fields. When you click "Continue", the configuration that you apply is added to API Data records available under Configuration > Automation > API Data. You can add a filter on Key = "portal_field_config" to find what was created and either amend or delete as required. At the time of writing, there isn't an easy way to manipulate the API Data created but this may be improved at a later date.

5) Create the Case Portal Web Process

On this screen, the plugin displays the processes and scripts that will be setup on your database to support the Case Portal. The plugin creates a new Web Process called "Case Portal" which you can access from Start > Configuration > Automation > Processes > Web Processes after you have completed this step. There are 48 parameters that can be configured on this process to support your business requirements of which the remainder of this plugin will guide you through the configuration of these.

Once you have completed the installation of the plugin, on step 11 - a URL to the Case Portal is provided. This can be passed to your web developers who will be able to configure an iFrame on your website to make the Case Portal accessible to your customers. Alternatively, you may decide to simply provide the direct link.

6) Configure Reports

To allow you to have full control over which cases are visible on the Portal, the process uses 2 reports, one for open cases, one for closed. You can control which Cases are visible by changing the criteria of these reports.

Two Report Templates are available - only use these rather than creating the reports from scratch. This is because the Portal needs certain columns to be available and is expecting the columns to be named a certain way. You should therefore not delete any columns from the report, nor edit any column names.

You can however add as many extra columns as you wish to each report such as Custom Fields specific to your business. These columns can be displayed in the Open/Closed Cases views on the Case Portal, allowing users the ability to search and sort the view by these columns. See Step 8 and the Show Columns parameter for setting up these views.

  1. Click Start > New > Report > Create a report from a template report and choose "Template - Support Portal - Open Cases".

    template-report-open-cases.png

  2. Name the report appropriately, so that it is clear that it should not be edited or deleted, as this would affect the Portal.

  3. Add a column for "Impact" (this is a newly created custom field) and ensure that it is named "Impact", plus any other columns that you want to display to the customer.

  4. Add a criteria for "'Exclude from Portal?' is false", plus any other criteria to restrict which cases are displayed, for example, only those of a certain Case Type.

  5. Open the calculated "Status" column. This controls the Status that the customer will see based on the status of the case, using the following formula:

    CASE status_name
    WHEN 'New' THEN 'New'
    WHEN 'In progress' THEN 'In Progress'
    WHEN 'Email received' THEN 'Awaiting Support Response'
    WHEN 'Updated by customer' THEN 'Awaiting Support Response'
    WHEN 'Awaiting customer response' THEN 'Awaiting Customer Response'
    WHEN 'Closed' THEN 'Closed'
    ELSE 'In Progress'
    END

    For example, if the Case Status is  "Email received" or "Updated by customer", then in the Portal the customer will instead see "Awaiting Support Response". You should add new lines in here for any other Case Statuses that you use, as if they are not specifically mentioned, the customer will see "In Progress". You can also amend the output to suit your business better, for example, the Workbooks own Portal might instead says "Awaiting response from Workbooks Support".

  6. Save and close the report.

  7. Repeat Steps 1 to 6 for  "Template - Support Portal - Closed Cases"

7) Set up Email Sender & Email Templates

When sending an Invite to the Portal, or when someone clicks on the 'Forgotten Password' link, Workbooks will send an email using Email Templates. To enable this functionality you will need to configure your email settings to allow Workbooks to send emails on behalf of you. If you haven't already completed this configuration previously, our Knowledge Base article, here, shows how to configure email settings. Once you have configured your account click the "Refresh" icon and select the relevant email account. Alternatively, you select an existing one from the list.

Next, you will need to create Email Templates. Templates are available in our Email Template Library. Click Start > Marketing > Templates > New Template. Choose to create a template for "A specific record type" and then choose "People". You should be provided with the option to choose a template from the list. The templates you need to create are "Case Portal - Registration" and "Case Portal - Forgotten Password".

case-portal-email-templates.png

You can edit the wording in the templates and add in your branding as required. However, do not change or delete the hyperlink, as this contains a required placeholder @link@. The Case Portal replaces this placeholder with the correct registration / forgotten password URL as new people register or request a password reset.

After you have created both Email Templates on your database, click the refresh icon within the plugin, this should populate the picklist with the available options from your database. Set both the Registration Email and Forgotten Password picklists to use the new Email Templates you have just configured.

portal_templates.png

8) Configure Case Settings (Including Queues), Company Details and the Case Portal's "All Open/Closed Cases" views

This step of the plugin allows you configure two queues that are used by the Case Portal for new Cases and also Case updates.

  • When a new Case is created via the Portal, it can be assigned to a Queue to then triage by your team. 
  • When a Case is updated via the Portal in Workbooks, it is added as an Activity record related to the Case. You can also control which Queue updates provided by a customer are assigned to in this screen.

If you wish, you can leave these options blank and all Case creations and updates will be assigned to the Automation user.

plugin_queues.png

If the queue that you wish to use does not exist, manually create it and then click the refresh button beside the picklist. You should see the new queue listed. For more information on creating Queues in Workbooks, see here.

Below this section, still within Step 8, you can configure your companies details. These will be displayed on the Case Portal to personalise on screen help texts and the like. You can provide the following information:

  • Company Name: The name of your company as you want it to appear to Portal users - you can select your Own Organisation here.

  • Support Website/Knowledge Base URL: Enter the URL for the 'Help' or 'Knowledge Base' part of your website in this parameter. This will be made visible in the ‘Help’ section of the Portal.

  • Company Logo URL: Enter the URL of the logo to be displayed in the top left of the Portal, normally your Company logo. To get the URL, first upload the image to your Upload Library if it is not stored there. When you do this, he Upload Library will then provide you with an 'External URL' - copy this into this parameter.

  • Privacy Policy URL: On the login page, a notification will pop up informing users that "This Portal uses cookies to ensure you get the best possible experience when using this service. See our Privacy Policy". Set this parameter to the URL where you company privacy policy is hosted, which is where the users will be redirected to if they click on 'Privacy Policy'.

Further down the screen, still on Step 8, you can configure the default values that are set on a Case when it is created or updated via the Case Portal. Under the Case Settings section, the following picklists are available:

  • Default Case Source: The values here are from the 'Case Sources' picklist. You must select a value here.

  • Default Case Status for Closed Cases: The values here are from the 'Case Statuses' picklist. You must select a value here.

  • Default Case Status for New Cases: The values here are from the 'Case Statuses' picklist. You must select a value here.

  • Default Case Status for Case updates: The values here are also from the 'Case Statuses' picklist. You must select a value here.

  • Default Case Type for New Cases: The values here are also from the 'Case Types' picklist. Select a value or leave blank if you do not wish to set this field

Finally, at the bottom of the screen for Step 8, you can configure the look and feel of the Open/Closed Cases view within the Case Portal. The settings that are configurable are as follows:

  • Show Case Resolution: When the customer is viewing an Open or Closed Case, you can choose to show the Case Resolution in a separate tab. If you set to Show, the information is pulled from the Case record, from the Resolution field. Alternatively, you could hide this tab and then use 'Public' Activities to track this information which would show under the Case History tab.
  • Show Case History: When the customer is viewing an Open or Closed Case, a tab is shown for the Case History i.e. the steps taken on a Case. The data shown here is 'Public' Activities related to the Case record. It also shows Emails that are sent to (including CC and BCC) or received by the Primary Contact of the Case. Data is shown in chronological order.
  • Show Case Description: When the customer is viewing an Open or Closed Case, a tab is shown for the Case Description. The data shown here is pulled from the Description field on the Case record.
  • Show Case Files: When the customer is viewing an Open or Closed Case, a tab is shown for Case Files. The tab shows any files that have been uploaded against a 'Public' Activity related to the Case. The files are downloadable.
  • Show Case Actions: When the customer is viewing an Open or Closed Case, you can choose whether you would like to allow your clients to Update/Close a Case. Currently these actions cannot be individually controlled, therefore setting this function to Hide, would make all Case records completely read only.
  • Default View - Open/Closed Cases: Once you have decided which tabs you would like to show on a Case within the Portal, you can decide tab shows by default. For instance, you may wish to show the Case History over the Case Description.
  • No Files - Help Text: The information text displayed on the Case Files tab when there are no files found against this Case. A default is provided but it can be overwritten as required if this is not suitable.
  • Individual Record Help Text: The information text displayed at the top of the Case when it is being viewed in the Case Portal. A default is provided but it can be overwritten as required if this is not suitable.
  • Open Cases View - Help Text: The information text displayed at the top of the all Open Cases view. A default is provided but it can be overwritten as required if this is not suitable.
  • Closed Cases View - Help Text: The information text displayed at the top of the all Closed Cases view. A default is provided but it can be overwritten as required if this is not suitable.
  • Enable File Uploads: If set to Show, a file upload field will appear on the Raise New Case screen within the portal. Files are uploaded against a  'Public' Activity and are visible in the portal for download again if required - NOTE: You would need to set the Show Case Files parameter to "Show" for this to be possible.
  • Open Cases Report: In Step 6, you configured a new Report to show Open Cases. You should select this report here.
  • Closed Cases Report: Also in Step 6, you configured a new Report to show Closed Cases. You should select this report here.
  • Show Columns: You can configure the columns that appear in the Open and Closed Case view, both of the views currently need to be configured to show the same columns. The columns that are selectable here are the ones you added to your Open Cases report in Step 6. The column names used in the report are shown in the Case Portal.
9) Configure a Custom Tab view in the Case Portal

NOTE: If this functionality is not required, then the "Show Custom Tab" picklist defaults to "Hide" so you can simply click Save Settings and move to the next step.

Alongside the standard Open/Closed Case tabs, the Case Portal can be configured to show a custom tab in the navbar. Where this might be useful is if you want to provide another type of Case to your users. For instance, let's use the following example - Your business sells machinery which have technical troubleshooting manuals that you would like to make available to your clients. You could configure the Case Portal to show a custom tab with this information. Currently, the Case Portal only supports one custom tab.

Create a Case report using one of the templates described in Step 6, you can then add as many custom fields as required for the view (remembering to leave the provided columns alone) and set the appropriate criteria. For instance, in this scenario, we only want to show Cases where the type is "Technical Manual".

From here, in Step 9 of the plugin set the "Show Custom Tab" to "Show". You will be presented with the following parameters:

  • Custom Tab Title: This text will be shown in the navbar next to the Open Cases / Closed Cases / Raise New Case options. In this scenario, you might set it to "Technical Manuals"
  • Custom Tab - All Records Info Text: This is the help text that is shown above the table of Cases, providing information to the customer about what records they are looking at in the view
  • Custom Tab - Individual Record Help Text: When the user clicks into a record from this view, there will be some help text at the top of the screen.
  • Custom Tab - No Files Help Text: If you have set the "Show Case Files" tab to "Show", then set some help text which will be shown to the user if there are no files available for the record they are viewing
  • Custom Tab - Show Case Resolution: Choose to show or hide the Case Resolution tab, driven from the Resolution field on Cases
  • Custom Tab - Show Case History: Choose to show or hide the Case History tab (as per the Open/Closed Cases view, this will show emails where the primary contact is in the to, cc or bcc of an email. It will also show the "public" Activities related to the Case
  • Custom Tab - Show Case Description: Choose to show or hide the Case Description tab, driven from the Description field on Cases
  • Custom Tab - Show Case Files: Choose to show or hide the Case Files tab (as per the Open/Closed Cases view, this will show the files uploaded against "public" Activities related to the Case
  • Custom Tab - Default View: Once you have decided which information you wish to display for these types of records, decide what the default view will be when a user first opens a record of this type
  • Custom Tab - Show Case Actions: Decide whether you would like the portal user to be able to update/close this type of Case. In the "Technical Manuals" example, you'd probably want to set this to "Hide" so that these types of Cases are read-only
  • Custom Tab - Report: Choose which report will drive the custom tab view of Cases
  • Custom Tab - Show Columns: Choose which columns from the report will be display in the table. The columns shown can be sorted and searched on within the custom tab view
10) Configure Help Screen within the Case Portal

On the Navbar of the Case Portal, you can display a ‘Help’ section help_0.png which points the user to other resources that provide useful information. This might be a URL to your Knowledge Base or an email/telephone number that they can call to reach you directly, rather than raising a Case via the portal.

help_section.png

On Step 10 of the plugin, you can configure what is shown here.

plugin_help.png

Click "Add New" for each section that you would like to add then provide the following information:

  • Title: In the example show above this is the "Visit our Website" text
  • Help Text:  In the example show above this is the "Find more information on our website" text
  • Button URL: In the example above, the button URL directs the user to the Workbooks website when the button is clicked
  • Button Text: In the example above, this simply configured to say "Visit our Website"

In the button URL you could include a "mailto:{YOUR_EMAIL}" link which would open a new email in the user's default email client with the email address you specified in the link. Alternatively, provide a callto:{YOUR_NUMBER} link so that the user can call you directly from their computer using a soft phone application if they have one installed.

11) Complete! See below for the remaining manual steps.

A URL to the Case Portal is provided on this screen. This can be passed to your web developers who will be able to configure an iFrame on your website to make the Case Portal accessible to your customers. Alternatively, you may decide to simply provide the direct link.


Manual Steps:

Now that you have installed the Case Portal plugin, there are a few manual steps that you need to complete to finish up.

Edit your Form Layouts

Cases

The plugin will have created the following fields on Cases, which you should also add to your Case Form Layouts as required:

TIP! You may wish to create a separate Form Layout, specifically for Case Portal cases. For example, you could create a Form Layout rule where the Case Source is equal to Portal

Other fields that are created are listed below:

  • Exclude from Portal? - a tickbox that can be used to stop specific cases from being displayed on the Portal.
  • Impact - a picklist with the values "High", "Medium" and "Low", which will be set by the customer via the Portal. This is so that they can let you know how urgent the case is, without affecting the standard "Priority" field, therefore allowing you to choose the correct priority.
People

The process will have created the following fields, which you should add to your Person Form Layout:

  • Authentication Blocked - allows you to block a registered Portal User from being able to log in.
  • Registered - a tickbox to show whether the Person has completed registration for the Portal.
  • First Login Time - The date and time that the Person first logged into the Portal.
  • Last Login Time - The date and time of the last time the Person logged into the Portal.
  • Last Login IP Address - The IP address from where the Person last logged in.
  • Portal Profile URL - The Portal allows users to upload a profile picture. The URL for the profile picture is stored in this field.
Activities

Finally, the process creates a picklist field on an Activity, called "Activity Sub Type". This picklist contains 2 values, "Private" and "Public". Any activities related to the case that have a sub type of "Public" will be visible to the customer on the Portal.

This means that you can log steps taken against a case using a "Private" activity, and it will not be visible on the Portal, but you can also log the summary of a phone call with the customer, or details of the next steps that they need to follow, in a "Public" activity that will be visible on the Portal.

TIP! You may want to set up Record Templates that set this field, to make it easier for your Support Team to create the right type of activity, or you could set a default value of "Private" so that activities are not visible on the Portal unless specifically made "Public".

Set up the Invite Button Process

Go to Start > Configuration > Customisation > Record Types > People and open your Person Form Layout. If you have multiple Form Layouts for People, these steps will have to followed for each Form Layout.

Go to the Automation tab of the Form Layout and click New Button Process.

Set the fields as follows and then save:

  • Button Text:- The name of the Process that will show when you click on the 'Run Process' button on a Person record, e.g. "Invite Person to Case Portal".
  • Script Location:- Change this to "Script Library".
  • Script:- Choose the "Case Portal" script.
  • Enable:- Keep this as "true".
  • Run as:- We would advise setting this to the 'Automation' User to ensure that the process is running as someone with full capabilities.
  • Location:- If you have other button processes on People, you will need to choose where this shows in the list. Do not set this to "On Save".
  • Show Confirmation Message:- Keep this as "true".

invite-button-process.png

Save this and then navigate to the Parameters tab. There are two parameters that you need to set for the Invite process to work correctly.

  • mode: Set this to "Invite". This tells the underlying PHP code to send a registration email for the current person.
  • registration_email_template_name: The name of the email template that will sent out to a Person when you run this process.

Once you have configured these two parameters, click Save and Close on the process and then Save and Close the Form Layout.

As an additional step, we'd recommend that you create a test user for your Case Portal so that you can test things are working correctly after you have followed this guide. You can do this by creating a Person record for yourself, simply giving the record a name and a valid email address. From here, click Run Process > Invite Person. If you have configured your email settings correctly, this email should be delivered within a few seconds. The email will have a hyperlink to the Case Portal which you should click to set a password. Once you've set a password, you can then access as often as you like.

Finished!
That's it! You are now set up and can start inviting your customers to use the Case Portal.