Installing Diary Planner

This documentation sets up a single instance (application) of Diary Planner. It uses one calendar, one appointment type, and the example booking forms that come with the product.

Before you Start

Before installing Diary Planner, the following components also need to be set up.

Other Products

• Bookings and the bookings database tables
• Comms Template Manager
• Self Service
• User Requests

Users and User Groups

• SLOTBOOKINGADMIN website user group (for staff members who handle appointments)
• SLOTBOOKINGUSER website user group (for users who will make bookings)

The BP Slot Booking workflow process, which starts when a user makes a booking, can be started by the anonymous user, and the SLOTBOOKINGUSER and CITIZENS user groups. Your logged in users must be a member of one of these groups so they can make bookings.

Import the Content

Diary Planner includes:

• Templates:
  • Slot Book
  • Slot Booking
  • Slot Type
  • My Slot Bookings
  • Forms Service - Diary Planner Reporting
  • Forms Service - Diary Planner Appointment
• Forms in the GOSS - Diary Planner group:
  • Blue Prints
  • Dashboard
  • Default
  • Examples
• End points in the goss.BookAndPay.DiaryPlanner namespace
• The BP Slot Booking workflow process
• DiaryPlannerExample CTM templates

Create Articles

This zip includes the following articles: Diary Planner Example Articles(zip)[3KB]. Importing the articles should create all of the correct templates and article extra settings needed without having to edit them.

Security and Location

The Configuration root article above, ie the appointments (Slot Type templates) and calendars (Slot Book templates), should be placed in a shared content root that the citizen and staff sites have access to. It is important that these articles are not secured.

The calendars and appointment types are not designed to be viewed directly by anyone. The booking forms look up their article extras, and the calendars are related to the admin Slot Booking article. However there is a risk that a user could see them. For that reason the article extras of the calendar (Slot Book template) must have their visibility settings set to the SLOTBOOKINGADMIN user group:

Failing to do this will allow any user to see the appointment details, including names and appointment types, of other users.

Create the Configuration

Diary Planner configuration is in two parts, although (at the time of writing) most of the configuration in the Book and Pay end point isn't used.

The full configuration is described in Configuration. The following need to be set up as a minimum.

Bookings Configuration

In the end point config.[env].BookAndPay.getConfig

• slotBookTemplateId - Enter the template ID of the Slot Book template

Diary Planner Configuration

Diary Planner configuration exists at three levels: global, application and appointment.

While there are certain settings which must be set at the appointment level, anything not set there will fall back to the application level. Anything not set at the application level will fall back to the global settings.

For a full description see Diary Planner Settings. The following must be set as a minimum.

config.[env].DiaryPlanner.DiaryPlannerExample.ExampleAppointment.getConfig

The appointment level configuration. Every appointment type must have an article using the Slot Type template and a getConfig end point which has that article ID set in it.

• appointmentTypeArticleId - The article ID of the Slot Type article for this appointment type (ie the "Example Appointment" article ID)

config.[env].DiaryPlanner.DiaryPlannerExample.getConfig

The application level configuration. Each instance of Diary Planner should have this configuration. It is mainly used to override global settings.

• adminSlotBookingId - The article ID of the Slot Booking article (ie the "Administration Calendar" article ID)
• noOfAppointmentsToOffer - The number of appointments offered by the booking forms (default 5)
• fromAddress - The from address used by emails
• fromName - The from name used by emails
• linkSettings - The following settings must be correct for your platform, they are used by the booking forms to look up available appointments. They are also used to generate links that can be used in messages and emails. Enter the subsite names for your staff and citizen sites, for example:

let linkSettings = {
    admin: {
        subsite: "staff"
    },
    csu: {
        subsite: "staff"
    },
    citizen: {
        language: {
            EN: {
                subsite: "citizen"
            }
        }
    }
};

config.[env].DiaryPlanner.getConfig

The global configuration. If any of these settings are set at an application or appointment level, they'll be overridden.

To get the example working you only need to check and update the userRoles:

let userRoles = {
    "anonymousUserRole": "anonymous",
    "roles": [{
        "code": "admin",
        "siteUserGroups": ["SLOTBOOKINGADMIN"],
        "name": "Admin",
        "isAdmin": true,
        "isCSU": true,
        "canSelectAppointments": true
    }, {
        "code": "csu",
        "siteUserGroups": ["CSA_GENERAL"],
        "name": "CSU",
        "isAdmin": false,
        "isCSU": true,
        "canSelectAppointments": false
    }, {
        "code": "citizen",
        "siteUserGroups": ["CITIZENS", "SLOTBOOKINGUSER"],
        "name": "Citizen",
        "isAdmin": false,
        "isCSU": false,
        "canSelectAppointments": false
    }],
    "anonymousUserId": 1
};

• admin - This defaults to the SLOTBOOKINGADMIN group. Make sure your staff users who access the calendars and Processing Appointments
• csu - These users are staff members who Viewing and Managing Appointments on behalf of citizens
• citizen - Users in these groups can book appointments. To start the appointment booking workflow your regular site users also need to be in the SLOTBOOKINGUSER group
• anonymousUserId - The ID of the anonymous user

You can leave all the actionSettings and taskAssignment options as they are.

Troubleshooting

No Appointments Available

This is probably the most common problem. Check that the article extras of the calendar (Slot Book) article have availability set for the appointment type (and that by pressing "update" the availability has been added to the list beneath the button):

Also check in your booking form article that the article extras are using the correct appointment configuration end point:

Appointments Available but Error on Booking

If you can get all the way to the end of the booking form, but it errors when you submit, check that the Slot Book and Slot Type articles are not secured.