Central Extension Tutorial

The Caliper SDK can be used to make extensions for use by CSRs in our back-office tool, Central, using the Central request handler.

Note

If you do not have the sandbox version of Central, download it here

Developing Central extensions will be a familiar process if you have made an Online extension–the Central request handler uses the same HQ API calls, jinja templating, routing, and most of the other features described in other parts of the tutorial.

Note

The Central request handler has a central_user property similar to the online_user property of an online request handler, accessed via self.central_user. It contains the following properties:

self.central_user.user_id
self.central_user.csr_group_id
self.central_user.login_name
self.central_user.user_logon_id
self.central_user.hq_session_id

Below is a basic sample Central extension, CentralMessenger, designed to send a custom secure message to all users in a group. To run it:

1. Type q2 create_extension and select the Central Extension type. Name it CentralMessenger

2. Copy the below code into the appropriate files within the newly created extension

3. Type q2 install to install the extension as a form, then select where you want it to appear within Central navigation

4. Type q2 run to start the server

5. Open your sandbox Central and navigate to where you installed it during the install step

Walkthrough

This sample extension was designed to demonstrate the similarities between creating a Central Extension and an Online Extension.

• When a user first navigates to the form, the handler routes to the default() method.

  • The default method calls HQ to get a list of available groups.

  • It passes the group list to the index.html.jinja2 template where it displays the groups, as well as input fields for required data.

• Once the user provides the required data and clicks submit, the handler routes to submit().

  • There, the handler receives the data for subject, message_body, and group_id.

  • It then passes it to the HQ method SendSecureMessageToAllUsersInAGroup and sets the appropriate message to return to the Central user.

  • It then renders the message and the data sent using the submit.html.jinja2 template.

extension.pyindex.html.jinja2submit.html.jinja2

from q2_sdk.core.http_handlers.central_handler import Q2CentralRequestHandler
from q2_sdk.hq.hq_api.q2_api import GetGroupList, SendSecureMessageToAllUsersInAGroup

class CentralMessengerHandler(Q2CentralRequestHandler):

    CONFIG_FILE_NAME = 'CentralMessenger'

    def __init__(self, application, request, **kwargs):
        super().__init__(application, request, **kwargs)

    @property
    def router(self):
        router = super().router
        router.update({
            'default': self.default,
            'submit': self.submit,
            # Add new routes here
        })

        return router

    async def default(self, refresh_cache=False):
        get_group_params = GetGroupList.ParamsObj(
            self.logger,
            self.hq_credentials
        )

        hq_response = await GetGroupList.execute(get_group_params)
        group_list = hq_response.result_node.Data.DalGroupList.Q2_GroupList

        template = self.get_template(
            'index.html.jinja2',
            {
                'group_list': group_list
            }
        )
        return template

    async def submit(self):
        message_subject = self.form_fields.get('subject')
        message_body = self.form_fields.get('message_body')
        group_id = self.form_fields.get('group_ID')
        send_message_params = SendSecureMessageToAllUsersInAGroup.ParamsObj(
            self.logger,
            self.central_user.csr_group_id,
            message_subject,
            message_body,
            group_id,
            self.hq_credentials
        )

        response = await SendSecureMessageToAllUsersInAGroup.execute(
            send_message_params
        )
        success = response.success
        if success:
            message_success = "Message Sent Successfully"
        else:
            message_success = "Message Failed To Send"


        template = self.get_template(
            'submit.html.jinja2',
            {
                'message_success': message_success,
                'message_subject': message_subject,
                'message_body': message_body,
                'group_id': group_id,
                'csr_group': self.central_user.csr_group_id
            }
        )
        return template