Custom Endpoint (When checking/unchecking items)¶

Warning

The endpoint will be called BOTH if you check or uncheck the item.

So make sure to have an if statement so you can handle the two scenarios separately

You can per checklist item configure a custom endpoint that should be executed when checking or unchecking that item. The structure of that endpoint always needs a specific format. Below you can see an example.

In the limepkg_dynamic_checklist.checklist_template module you have tools for parsing and validating the payload so that you can focus on the logic instead. The parsing will result in a type dataclass so that you easily can work with it.

The endpoint needs to have a POST verb to be able to work, and it need to return a success status code (2XX) for the checklist item to actually be saved. So if you want to stop the user from checking/unchecking the item, you can return a failed success code. The return data needs to be valid JSON

Data provided to a custom endpoint¶

Name	Type	Description
item_id	`int`	id of the limeobject `checklist_item` that the user checked/unchecked
item_action	`limepkg_dynamic_checklist.checklist_template.ItemAction`	An enum saying if it was `CHECK`, `UNCHECK`, `IGNORE` or `UNIGNORE`
value [Deprecated]	`bool`	A flag for saying if it was a check or uncheck (`True` means trying to check, `False` means trying to unchecked)
ignore [Deprecated]	`bool`	A flag for saying if it was an ignore or unignore (Or just checked/unchecked) (`True` means trying to check, `False` means trying to unchecked)
owner_table	`str`	A string containg the name of the limetype that "owns" the checklist item i.e. `helpdesk`
checklist_template	`limepkg_dynamic_checklist.checklist_template.Template`	Dataclass Containg all configuration made for that specific checklist
checklist_item_template	`limepkg_dynamic_checklist.checklist_template.ItemData`	Dataclass Containg all configuration made for that specific checklist item
item_limeobject	`lime_type.LimeObject`	The Limeobject that corresponds to the checked/unchecked item
owner_limeobject	`lime_type.LimeObject`	The Limeobject of the owner of the checklist item i.e. a `helpdesk` object

Example endpoint that creates a history with custom text¶

from lime_type.limeobjects import LimeObject
import lime_webserver.webserver as webserver
import logging
from ..endpoints import api
import limepkg_dynamic_checklist.checklist_template as checklist_template
import flask
from http import HTTPStatus

logger = logging.getLogger(__name__)


class Example(webserver.LimeResource):
    """This is an example that does custom stuff"""

    def post(self):
        try:
            app = self.application
            payload = checklist_template.parse_custom_endpoint_payload(
                app=app,
                payload=flask.request.get_json(True)
            )
            item_title = payload.checklist_item_template.title

            uow = app.unit_of_work()
            history: LimeObject = app.limetypes.history()
            history_idx = uow.add(history)

            action_text = ""
            if payload.item_action == checklist_template.ItemAction.CHECK:
                action_text = "CHECK"
            elif payload.item_action == checklist_template.ItemAction.UNCHECK:
                action_text = "UNCHECK"
            elif payload.item_action == checklist_template.ItemAction.IGNORE:
                action_text = "IGNORE"
            elif payload.item_action == checklist_template.ItemAction.UNIGNORE:
                action_text = "UNIGNORE"

            history.properties.note.value = (
                f"MY CUSTOM ENDPOINT ON: {item_title} - {action_text}"
            )
            history.properties.type.set_by_key('comment')
            parent_prop = history.get_property(payload.owner_table)
            if parent_prop and parent_prop.is_relation():
                if payload.owner_limeobject:
                    uow.add(payload.owner_limeobject)
                    parent_prop.attach(payload.owner_limeobject)
            result = uow.commit()
            history = result.get(history_idx)
            return history.values(include_sys_values=True), HTTPStatus.CREATED

        except checklist_template.ValidationError as e:
            flask.abort(
                HTTPStatus.UNPROCESSABLE_ENTITY,
                f'Invalid payload: {e}')
        except Exception as e:
            logger.exception(e)
            flask.abort(
                HTTPStatus.INTERNAL_SERVER_ERROR,
                'Something bad happened, check logs for more details')


api.add_resource(Example, '/example/my-test/')

Messages and Error handling¶

Text message to user on success¶

You can control if a message should be shown to the user after your endpoint is run or not.

Translations

If you want the message to be localized, it's best to fetch translations in backend so that it works the same in both desktop and web client.

See example no how here

If you want the user to get a message

Make sure that your endpoint return one of the following:

Return a string:

return "Message to user"

Return a dict containing the message in a key called message:

return {
    "message": "Message to user"
}

If you don't want the user to get a message or anything.

Make sure that your endpoint doesn't return a string or a dict containing a string with key message.

Error handling¶

If your endpoint doesn't return a 2XX status code the item won't be checked/unchcked, i.e. you can cancel it.

If you want the user to get a customized error message you can do it by doing one of the following:

Return a string

from http import HTTPStatus

# Endpoint stuff...

return "My exception", HTTPStatus.BAD_REQUEST

Return a dict containing the message in a key called message:

This can be done in a few different ways, here's 2 examples:

Use the flask abort function:

import flask
from http import HTTPStatus

# Endpoint stuff...

flask.abort(HTTPStatus.BAD_REQUEST, "My exception")

Or by returning a dict directly:

from http import HTTPStatus

# Endpoint stuff...

return {
    "message": "My exception"
}, HTTPStatus.BAD_REQUEST

Using translations¶

# Import translation module
import lime_translation

# Endpoint stuff

# Here you can put in parameters
# that can be used as template codes in your string
# Maybe a limetype local name or whatever
params = {
    "example": "Example value"
}
lime_translation.get_text(
    app.language,
    "lib_name.my-translation-key",
    **params
)

Just replace your regular string with the result of the lime_translation.get_text function

How to configure a custom endpoint¶

In the Item settings of the Checklist builder you will have a field called: Custom Endpoint. That should contain the uri to your endpoint. So if your solution is named solution-customername and your endpoint have the url /example/my-test/

Then you should set the value solution-customername/example/my-test in the field.