Caluma companion app for periodic usage of forms.

There are forms you might want to use periodically. This project adds support for this by utilizing the meta-field of forms.

Your flux capacitor needs new plutonium once every two weeks. So you have a form refill-plutonium-in-flux-capacitor you want to use every two weeks.

This can be achieved with following interval inside the meta field of this form:

{
    "interval": {
        "interval": "P2W",
        "workflow_slug": "delorean-workflow"
    }
}

This will make sure, that exactly two weeks after the last refill, a new case will be opened for this form.

Now let's say, it's important to you, that this case is always opened on a monday (shortening the interval if needed). Further you want to set a start date, to make sure no case will be opened before that.

This can be achieved with following interval:

{
    "interval": {
        "interval": "2019-03-18/P2W",
        "weekday": 0,
        "workflow_slug": "delorean-workflow"
    }
}

• Handle periodic usage of forms
• Optionally set a start date
• Optionally force a specific weekday
• Will never start multiple cases for the same form

The meta-field is a JSONField and can be found on a variety of Caluma-objects. We're only interested in forms though.

caluma-interval checks the meta-field of forms for an interval-key.

Example:

{
    "interval": {
        "interval": "2018-03-01/P1Y2M10D",
        "weekday": 1,
        "workflow_slug": "my-test-workflow"
    }
}

ISO8601 time interval notation.

We use {{startdate}}/{{duration}}, where startdate is optional. If omitted, the case will be opened immediately.

For duration we use a subset of ISO8601 duration without time.

You can find the regex we use below in ValidationClass.

An optional weekday (zero-indexed integer). This makes sure, that only on this weekday a case for this form will be started.

This will never exceed the configured interval.

The slug for the corresponding workflow.

You can configure caluma_interval with environment variables or CLI arguments, whereas CLI arguments take precedence.

usage: __main__.py [-h] [-c STRING] [-i STRING] [-s STRING] [-u STRING] [-d]
                   [-v]

Caluma companion app for periodic usage of forms

optional arguments:
  -h, --help            show this help message and exit
  -c STRING, --caluma-endpoint STRING
                        defaults to "http://caluma:8000/graphql"
  -i STRING, --oidc-client-id STRING
  -s STRING, --oidc-client-secret STRING
  -u STRING, --oidc-token-uri STRING
  -d, --debug           print debug messages
  -v, --version         show program's version number and exit

The corresponding environment variables are:

• CALUMA_ENDPOINT - defaults to http://caluma:8000/graphql
• OIDC_CLIENT_ID
• OIDC_CLIENT_SECRET
• OIDC_TOKEN_URI

Additional environment variables for when using the docker image:

• CALUMA_HOST - defaults to caluma
• CALUMA_PORT - defaults to 8000

To enable oidc authentication over plain http (only for testing!), set OAUTHLIB_INSECURE_TRANSPORT to 1.

As Caluma uses OpenID Connect (OIDC), we need to fetch a token from the OIDC provider.

For this you have to provide a client id, client secret and a token uri.

If none of them are provided, the client will make unauthenticated requests, which (hopefully) will fail in your prod setup.

You may want to add a custom ValidationClass to Caluma in order to validate the content of meta['interval']:

import re
from datetime import datetime

from caluma.core.validations import BaseValidation, validation_for
from caluma.form.schema import SaveForm
from caluma.workflow.models import Workflow
from rest_framework import exceptions


# Regex to parse ISO8601 periods WITHOUT time information
ISO8601_PERIOD_DATE_REGEX = re.compile(
    r"^P(?!$)"
    r"(\d+(?:[,\.]\d+)?Y)?"
    r"(\d+(?:[,\.]\d+)?M)?"
    r"(\d+(?:[,\.]\d+)?W)?"
    r"(\d+(?:[,\.]\d+)?D)?$"
)


def validate_interval(interval):
    interval_list = interval["interval"].split("/")
    if len(interval_list) == 2:
        try:
            datetime.strptime(interval_list[0], "%Y-%m-%d")
        except ValueError:
            raise exceptions.ValidationException("Failed to parse startdate!")
    elif len(interval_list) > 2:
        raise exceptions.ValidationException("Failed to parse interval!")

    if not ISO8601_PERIOD_DATE_REGEX.match(interval_list[-1]):
        raise exceptions.ValidationException("Failed to parse period!")


class FormIntervalValidation(BaseValidation):
    @validation_for(SaveForm)
    def validate_save_form(self, mutation, data, info):
        if "meta" not in data and "interval" not in data["meta"]:
            return data
        interval = data["meta"]["interval"]

        if "interval" not in interval:
            raise exceptions.ValidationException("Interval must be set!")

        if "workflow_slug" not in interval:
            raise exceptions.ValidationException("workflow_slug must be set!")

        try:
            Workflow.obj.get(slug=interval["workflow_slug"])
        except Workflow.DoesNotExist:
            raise exceptions.ValidationException(
                "Failed to get workflow with provided workflow_slug!"
            )

        if "weekday" in interval:
            if not interval["weekday"] >= 0 <= 6:
                raise exceptions.ValidationException(
                    "Weekday must be an integer from 0 to 6!"
                )

        validate_interval(interval['interval'])

interval:
  image: projectcaluma/caluma-interval:latest
  build:
    context: .
  depends_on:
    - caluma

We use following tools in order to standardize development and releases:

• flake8
• black
• isort
• commitlint

Pre commit hooks is an additional option instead of executing checks in your editor of choice.

First create a virtualenv with the tool of your choice before running below commands:

pip install pre-commit
pip install -r requirements-dev.txt -U
pre-commit install
pre-commit install --hook=pre-commit
pre-commit install --hook=commit-msg