Introduction

What are modules for? Modules are tailored for end customers and primarily designed for tasks like appointment booking or cancellation. Modules do not necessitate user login, offering a hassle-free experience for accessing their functionalities in a simple way.

To create a module, you will need the following:

Goal

At the end of this article you will have a functioning new module, that customers can look up online and book appointments with.

Story

The ACME Corporation offers a wide range of products and customers are not always sure which one is fitted to their needs. That is the reason ACME Corporation has commissioned the IT solutions developer Meg Abyte to develop a support appointment module for their new bookingtime software.

The module will show three options for the costumers to choose from:

• Product Consultation
• Repairs
• Warranty

Customers will be able to have 30 minute long calls with experienced employees and get first hand information.

Before deploying the new module to ACME, Meg wants to create a development environment, thus "ACME Corporation DEV" is born. That way the software can be easily developed and tested.

Requirements

The first step to develop a module is to create the necessary accounts. See our "How to create a bookingtime account and developer account". The accounts start all involving processes and will be needed to create the basic structures.

When this user account is created, it will be the first user of this organization and simultaneously the admin.

Create the module in the bookingtime developer area

On the left side of the developer server start page, click the "Modules" section or click the hyperlink on the "Modules" tile.

This is the menu where all modules for the current organizations will be listed. To create a new module, click on the "+ Add module" button.

General information

Modules are separated into "General information" and "Details".

By default, modules will be activated on creation. Multiple installations of a module are possible, for example, to map different use cases. For instance, one module may serve the ACME Support team, while another could be tailored for the ACME Marketing department. This way a different URL will be generated and can be handed out to the customers to show a different list of appointment templates in the booking module.

Furthermore there is an option, whether appointment templates can be chosen by users or not. If enabled, users can choose appointment templates from the organization. This means that only certain types of appointments can be seen and booked by the customer in the booking module.

The parameters "Name", "Short description", "Description" have an optional "i18n" (internationalization) setting, to support different languages.

The required parameters to create a module are: "Name", "Short description", "Description", "Version", "Language".

Details

The version number field is used to input and track the specific software release.

To access the module, a "base" URL can be entered in the field "Web App URL". The base URL for ACME would look like this: "http://www.acme.com/booking-module/".

Access rights refer to permissions that can be given to the module. For example, a module with the "appointmentAdd" permission can create appointments in the associated calendar.

For this example, custom entities and the OAuth redirect URLs are not important.

The necessary permission for a customer to book an appointment are the following:
"appointmentAdd", "bookingResource", "bookingSlot", "bookingTemplate" and "organization".

Placeholder can be implemented in the URL. For example it is possible to enter the following URL: https://www.acme.com/booking-module/?organization=ORGANIZATION_ID&moduleConfig=MODULE_CONFIG_ID

After entering all required information, you will be redirected to the list of available modules.

Extracting the clientId

For a later step, "Develop your first module", we need to extract the clientId of the newly created bookingtime module.

1. On the "Module overview" site, click the three dots under "Actions".
2. Click "Display".
   
   
   
   
3. The clientId is listed as the second information on the "General information" part.
4. Keep the tab open, or copy it. 

Creating the basic structure

The organisation

The organization is the highest entity in the hierarchy. It connects to apps, modules, appointments, appointment templates, employees, customers, contracts and licenses.

To create a test organization, simply click the "Add Organization" button on the left side of the "Developer Service Portal".

Choose a name and click on "Create".

Clicking the "Create" button, a message will be shown with the option to switch to the newly generated organization.

If you want to switch between different organizations, it is possible to click the "Switch organizations" button in the upper part of the blade menu on the left.

Install the module

The module we created earlier is now in the "Store", but needs to be installed to the organization.

1. Head to the "Store" of the organization. 
2. Click on the "Modules" tile.
3. Choose the developed module, in this case "ACME_Support_Module".
4. Click the "+ Install" button and optionally enter an internal note.
   
   
   
   
5. Click the "Install" button.

The module is now installed for this organization and will be fully accessible, after it is developed and reachable under the configured URL.

Develop your first module

All preparations are made to start developing the actual module. Meg found the bookingtime PHP SDK on Github and noticed a code example. After customizing the code, the very first module was developed.

<?php

        //bookingtime module SDK can be installed via composer
        use bookingtime\phpsdkmodule\Sdk;
        
        //Create a new SDK object, this clientId can be found in developer service -> "Modules" under: "Actions" -> "Display" -> "clientId"
        //In this case we need no clientSecret
        $sdk = new Sdk(
          'U8oy978MJteZ0UhvyA9Q2B9VhFYmgBi0QCAhh5y5KBRF1b8dMKLeSBsuBLOemXmY',
          '',
          ['locale' => 'en']
        );
        
        // Load moduleConfig for submitted organizationId/moduleConfigId
        // The organizationId and moduleConfigId are usually transmitted directly as GET variables to the module URL.
        // E.g. URL: http://www.acme.com/booking-module/book?organizationId=xxx&moduleConfigId=xxx
        // SDK calls the following API URL:
        // https://api.bookingtime.com/module/v3/en/organization/{organizationId}/moduleConfig/{moduleConfigId}/show
        // API Documentation:
        // https://service.bookingtime.com/apidoc/module#operation/showModuleConfig
        // In this example, the modulConfig will not be used. It could be used e.g. for individual moduleSettings for different organizations.
        $moduleConfig = $sdk->moduleConfig_show([
          'organizationId' => 'f6xsZPydxk9P7VneZIkoFdmtvF2v5xeh',
          'moduleConfigId' => '5fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        ]);
        
        // List all available bookingTemplates
        // We want to show the user a list of all booking templates, in our case: Product Consultation, Repairs, Warranty
        // SDK calls the following API URL:
        // https://api.bookingtime.com/module/v3/en/organization/{organizationId}/bookingTemplate/list
        // API Documentation:
        // https://service.bookingtime.com/apidoc/module#operation/listBookingTemplate
        $bookingTemplateArray = $sdk->bookingTemplate_list([
          'organizationId' => 'f6xsZPydxk9P7VneZIkoFdmtvF2v5xeh',
        ]);
        
        //place your application code here (user should select a bookingTemplate)...
        
        // Get a list of possible bookingSlots for the selected bookingTemplate and week
        // If the user has selected a bookingTemplate, he can choose a free slot for his appointment
        // SDK calls the following API URL:
        // https://api.bookingtime.com/module/v3/en/organization/{organizationId}/bookingTemplate/{bookingTemplateId}/bookingSlot/year/{year}/week/{week}/listWeek
        // API Documentation:
        // https://service.bookingtime.com/apidoc/module#operation/listBookingSlotWeek
        $bookingSlotArray = $sdk->bookingSlot_listWeek([
          'organizationId' => 'f6xsZPydxk9P7VneZIkoFdmtvF2v5xeh',
          'bookingTemplateId' => 'fcrVx2aWQzDnd1MZkEeVbVDt6wuFCJIL',
          'year' => '2024',
          'week' => '39',
        ]);
        
        //Place your application code here (show calendar and bookingSlots)...
        //Place your application code here (ask user for gender, email, name and notes)...
        
        // Finally book a new appointment with selected bookingSlots and user-data
        // This will create a new appointment and customer entity in the system
        // SDK calls the following API URL:
        // https://api.bookingtime.com/module/v3/en/organization/{organizationId}/appointment/add
        // API Documentation:
        // https://service.bookingtime.com/apidoc/module#operation/addAppointment
        $appointment = $sdk->appointment_add([
          'organizationId' => 'f6xsZPydxk9P7VneZIkoFdmtvF2v5xeh',
        ], [
          'bookingSlotId' => 'brKiD2gtaMUZmHO3rLhecHkqdEr6d2gv',
          'notes' => 'My first appointment',
          'customer' => [
              'gender' => 'MALE',
              'firstName' => 'John',
              'lastName' => 'Deaux',
              'email' => 'j.deaux@email.com',
          ],
        ]);
        
        //place your application code here (show user an success page)...
        

    The Javascript example code will follow soon.
      
    

Testing your module

Meg has created the initial module and is keen to assess its functionality. However, certain requirements and configurations must be addressed before appointments can be scheduled. Booking appointments necessitates the presence of an appointment template. Once this is in place, customers with access to the booking module link can proceed to schedule appointments, which can then be viewed on the calendar app. This scenario presents an optimal test scenario for the newly developed booking module.

Upon organization creation, fundamental templates and configurations are established, ensuring ease of use and default testability of our software. Appointments can be booked instantly.

Appointment Templates

Since the ACME wants three different options for their module, we will need three appointment templates. Meg found an existing appointment template, which is generated with the creation of the organization, but won't work with developed module. To match the needs of the ACME Corp, Meg creates new appointment templates with the following steps.

1. Head to the "Settings" of the organization.
2. Click on the "Appointment Template" tile.
3. In the bottom, left corner of the window, click on "+ Appointment Template".
4. Enter "Product Consultations" and hit "Confirm". A new dialog opens and shows the newly created appointment template.
5. At last, the appointment templates needs to be activated. Select the "Activate template" tick box and click on the "Save" button in the upper right corner of the window.
6. Repeat the steps from 3. to 5. for the options "Repairs" and "Warranty".

Booking Module

Accessing the URL of the module

1. Head to the "Store" of the organization. 
2. Click on the "Modules" tile.
3. Choose the developed module, in this case "ACME_Support_Module".
4. Click on the "Settings" button in the upper, right corner of the window.
   
   
5. A blade menu opens up on the right side of the screen, showing the "Link to module" URL.
6. After clicking on the URL, a new tab opens with the configured appointment templates.

The first booking of an appointment

To test the module, simply select the desired option. The process guides the customer till the end and will show a summarization of all entered details.

1. Select one of the given choices.
2. Select an employee. The admin will be the selected employee, if no other employees have been created.
3. Select a date and a time of the day.
   
   
   
   
4. At the last step, give details about yourself, or an made up customer.
   
   
   
5. After clicking "Book appointment" a success message will come up and show all entered details.
   

Congratulations, you developed and tested your first module! 🎉

Important notice: Currently there is no way to install a module to another organization, except to contact bookingtime. In the future, there will be an opportunity to do so. 

Next Steps

• Module Settings
• Create a module config