Backend Modules

The backend of the OpenIMIS system consists of several essential modules that work together to provide comprehensive functionality. Each module serves a specific purpose and contributes to the overall operation of the system. Below is the list of backend modules:

1. openimis-be-individual_py

   The openimis-be-individual_py module is dedicated to handling individual references within the OpenIMIS system. It provides services and functionalities for managing individual records, including creating, updating, and deleting individual data.

2. openimis-be-social_protection_py

   The openimis-be-social_protection_py module focuses on managing social protection-related information within the OpenIMIS system. It handles various aspects of social protection data, ensuring proper data management and processing.

3. openimis-be-tasks_management_py

   The openimis-be-tasks_management_py module is responsible for managing tasks and activities within the OpenIMIS system. It helps streamline workflow by handling task assignment, tracking, and completion.

4. openimis-be-opensearch_reports_py

   The openimis-be-opensearch_reports_py module provides functionalities for generating and accessing reports in the OpenIMIS system. It allows users to search and retrieve relevant reports based on specific criteria.

5. openimis-be-workflow_py

   The openimis-be-workflow_py module is dedicated to managing data upload.

6. openimis-be-payment_cycle_py

   The openimis-be-payment_cycle_py module is responsible for managing payment cycles within the OpenIMIS system. It handles payment-related processes, including scheduling, calculations, and disbursements.

7. openimis-be-calcrule_social_protection_py

   The openimis-be-calcrule_social_protection_py module is specialized in managing calculation rules for social protection data within the OpenIMIS system. It ensures accurate and consistent calculation of benefits and entitlements.

These modules work in tandem to create a robust backend infrastructure for the OpenIMIS system, enabling efficient data management, task handling, and reporting capabilities.

Please note that the list above provides an overview of the backend modules in the OpenIMIS system. Each module may have its own set of functionalities, services, and configurations, which can be further explored through specific documentation and resources.

OpenIMIS Backend Individual Reference Module Documentation

OpenIMIS Backend Social Protection Reference Module Documentation

Introduction

The OpenIMIS Backend Social Protection Reference Module is an integral part of the OpenIMIS system. This module is dedicated to handling social protection-related information, including benefit plans, beneficiaries, and group beneficiaries. It is designed to be deployed as a module of openimis-be_py, the OpenIMIS backend application.

This documentation aims to provide a comprehensive guide on how to utilize, configure, and interact with the Social Protection Reference Module effectively.

ORM Mapping

The module uses Object-Relational Mapping (ORM) to map data from the database to Python objects. The following ORM mappings are used:

• social_protection_benefitplan, social_protection_historicalbenefitplan -> BenefitPlan: Represents a social protection benefit plan entity.

• social_protection_beneficiary, social_protection_historicalbeneficiary -> Beneficiary: Represents a social protection beneficiary entity.

• social_protection_benefitplandatauploadsrecords, social_protection_historicalbenefitplandatauploadsrecords -> BenefitPlanDataUploadRecords: Represents data upload records associated with a benefit plan.

• social_protection_groupbeneficiary, social_protection_historicalgroupbeneficiary -> GroupBeneficiary: Represents a group beneficiary entity.

Developers can access and manipulate social protection data using these mapped objects, which abstract away the underlying database complexities.

GraphQL Queries

The module provides several GraphQL queries to retrieve social protection-related information:

• benefitPlan: Retrieves benefit plan data based on specified criteria.

• beneficiary: Retrieves beneficiary data based on specified criteria.

• groupBeneficiary: Retrieves group beneficiary data based on specified criteria.

• beneficiaryDataUploadHistory: Retrieves the data upload history of beneficiaries.

• bfCodeValidity: Validates the beneficiary code.

• bfNameValidity: Validates the beneficiary name.

• bfSchemaValidity: Validates the beneficiary schema.

• beneficiaryExport: Exports beneficiary data.

• groupBeneficiaryExport: Exports group beneficiary data.

These GraphQL queries provide a flexible and efficient way to retrieve relevant social protection data.

GraphQL Mutations

The Social Protection Reference Module offers GraphQL mutations to manage social protection data. Each mutation emits default signals and returns standard error lists following the conventions of openimis-be-core_py.

List of available mutations:

• createBenefitPlan: Creates a new benefit plan record.

• updateBenefitPlan: Updates an existing benefit plan record.

• deleteBenefitPlan: Deletes a benefit plan record.

• createBeneficiary: Creates a new beneficiary record.

• updateBeneficiary: Updates an existing beneficiary record.

• deleteBeneficiary: Deletes a beneficiary record.

• createGroupBeneficiary: Creates a new group beneficiary record.

• updateGroupBeneficiary: Updates an existing group beneficiary record.

• deleteGroupBeneficiary: Deletes a group beneficiary record.

These mutations enable seamless management of social protection data within the OpenIMIS system.

Services

The module provides the following services:

• BenefitPlanService: Offers methods to create, update, and delete benefit plan records.

• BeneficiaryService: Provides methods to create, update, and delete beneficiary records.

• GroupBeneficiaryService: Offers methods to create, update, and delete group beneficiary records.

• BeneficiaryImportService: Provides methods to import beneficiaries.

Developers can interact with these services to perform CRUD (Create, Read, Update, Delete) operations and handle beneficiary imports.

Configuration Options

The behavior of the Social Protection Reference Module can be customized through configuration options, which can be modified via core.ModuleConfiguration. The available configuration options are:

• gql_benefit_plan_search_perms: Specifies the required rights to call the benefitPlan GraphQL query. (Default: ["160001"])

• gql_benefit_plan_create_perms: Specifies the required rights to call the createBenefitPlan GraphQL mutation. (Default: ["160002"])

• gql_benefit_plan_update_perms: Specifies the required rights to call the updateBenefitPlan GraphQL mutation. (Default: ["160003"])

• gql_benefit_plan_delete_perms: Specifies the required rights to call the deleteBenefitPlan GraphQL mutation. (Default: ["160004"])

• gql_beneficiary_search_perms: Specifies the required rights to call the beneficiary and groupBeneficiary GraphQL queries. (Default: ["170001"])

• gql_beneficiary_create_perms: Specifies the required rights to call the createBeneficiary and createGroupBeneficiary GraphQL mutations. (Default: ["160002"])

• gql_beneficiary_update_perms: Specifies the required rights to call the updateBeneficiary and updateGroupBeneficiary GraphQL mutations. (Default: ["160003"])

• gql_beneficiary_delete_perms: Specifies the required rights to call the deleteBeneficiary and deleteGroupBeneficiary GraphQL mutations. (Default: ["170004"])

• check_benefit_plan_update: Specifies whether the update of a Benefit Plan should be approved. (Default: True)

Developers can adjust these options to control access, permissions, and behavior related to social protection data.

OpenIMIS Modules Dependencies

The Social Protection Reference Module relies on the following modules:

• core: Provides core functionality and utilities for the OpenIMIS system.

• policyholder: Handles policyholder-related information.

• individual: Manages individual references within the OpenIMIS system.

Ensure that these modules are correctly installed and configured for the Social Protection Reference Module to function properly.

OpenIMIS Backend Task Management Reference Module Documentation

Introduction

The OpenIMIS Backend Task Management Reference Module is a crucial component of the OpenIMIS system. This module is dedicated to managing tasks and activities within the system. It provides services, functionalities, and GraphQL queries related to task handling. The Task Management Reference Module is designed to be deployed as a module of openimis-be_py, the OpenIMIS backend application.

This documentation aims to provide a comprehensive guide on how to utilize, configure, and interact with the Task Management Reference Module effectively.

ORM Mapping

The module uses Object-Relational Mapping (ORM) to map data from the database to Python objects. The following ORM mappings are used:

• task_management_task, task_management_historicaltask -> Task: Represents a task entity.

• task_management_taskgroup, task_management_historicaltaskgroup -> TaskGroup: Represents a group of tasks.

• task_management_taskexecutor, task_management_historicaltaskexecutor -> TaskExecutor: Represents a task executor.

Developers can access and manipulate task-related data using these mapped objects, which abstract away the underlying database complexities.

GraphQL Queries

The module provides several GraphQL queries to retrieve task-related information:

• task: Retrieves task data based on specified criteria.

• taskGroup: Retrieves task group data based on specified criteria.

• taskExecutor: Retrieves task executor data based on specified criteria.

These GraphQL queries provide a flexible and efficient way to retrieve relevant task data.

Services

The module provides the following services:

• TaskService: Offers methods to create, update, and delete tasks, execute tasks, and mark tasks as completed or resolved.

• TaskGroupService: Provides methods to create, update, and delete task groups.

• TaskExecutorService: Offers methods to create, update, and delete task executors.

Developers can interact with these services to perform various operations related to task management.

Configuration Options

The behavior of the Task Management Reference Module can be customized through configuration options, which can be modified via core.ModuleConfiguration. The available configuration options are:

• gql_task_group_search_perms: Specifies the required rights to call the taskGroup GraphQL query. (Default: 190001)

• gql_task_group_create_perms: Specifies the required rights to call the createTaskGroup GraphQL mutation. (Default: 190002)

• gql_task_group_update_perms: Specifies the required rights to call the updateTaskGroup GraphQL mutation. (Default: 190003)

• gql_task_group_delete_perms: Specifies the required rights to call the deleteTaskGroup GraphQL mutation. (Default: 190004)

• gql_task_search_perms: Specifies the required rights to call the task GraphQL query. (Default: 191001)

• gql_task_create_perms: Specifies the required rights to call the createTask GraphQL mutation. (Default: 191002)

• gql_task_update_perms: Specifies the required rights to call the updateTask GraphQL mutation. (Default: 191003)

• gql_task_delete_perms: Specifies the required rights to call the deleteTask GraphQL mutation. (Default: 191004)

Developers can adjust these options to control access and permissions related to task management operations.

OpenIMIS Modules Dependencies

The Task Management Reference Module relies on the following modules:

• core: Provides core functionality and utilities for the OpenIMIS system.

Ensure that the core module is correctly installed and configured for the Task Management Reference Module to function properly.

Creating Execution Action Handlers and Business Event Handlers

The module allows the creation of execution action handlers and business event handlers for tasks. To implement custom handling of task execution or completion, developers need to bind to specific signals.

Binding to Task Execution Signal

To create an execution action handler, bind to the task_service.resolve_task signal using the handler_hook function. The handler should check the specific executor_action_event of the task.

Example:

# In signals.py of any module
def bind_service_signals():
    bind_service_signal(
        'task_service.resolve_task',
        handler_hook,
        bind_type=ServiceSignalBindType.AFTER
    )

def handler_hook(**kwargs):
    # Custom handling logic for task execution action
    pass

Binding to Task Completion Signal

To create a business event handler for task completion, bind to the task_service.complete_task signal using the handler_hook function.

Example:

# In signals.py of any module
def bind_service_signals():
    bind_service_signal(
        'task_service.complete_task',
        handler_hook,
        bind_type=ServiceSignalBindType.AFTER
    )

def handler_hook(**kwargs):
    # Custom handling logic for task completion business event
    pass

openIMIS Backend opensearch_reports reference module

OpenIMIS Backend Workflow Reference Module Documentation

Introduction

The OpenIMIS Backend Workflow Reference Module is a crucial component of the OpenIMIS system. This module is dedicated to managing workflows and integrating with various workflow systems. It provides services and functionalities to register workflow systems, query available workflows, and execute workflows. The Workflow Reference Module is designed to be deployed as a module of openimis-be_py, the OpenIMIS backend application.

This documentation aims to provide a comprehensive guide on how to utilize and interact with the Workflow Reference Module effectively.

Services

The Workflow Reference Module provides the following service:

• WorkflowService: Offers methods to register workflow systems, query available workflows, and execute workflows.

Developers can interact with this service to perform various operations related to workflows.

Registering Workflow Systems

The Workflow Service can be extended with custom adaptors to integrate with new workflow systems. Any adaptor must extend workflow.systems.base.WorkflowAdaptor and return triggers as implementations of workflow.systems.base.WorkflowHandler.

Example:

# Example of extending WorkflowAdaptor
class CustomWorkflowAdaptor(WorkflowAdaptor):
    def get_triggers(self):
        # Implement logic to retrieve triggers from the custom workflow system
        return [CustomWorkflowHandler1(), CustomWorkflowHandler2(), ...]

# Register the custom workflow adaptor
WorkflowService.register_system_adaptor(CustomWorkflowAdaptor)

Querying Workflows

Querying available workflows can be done using the WorkflowService.get_workflows service. All registered workflow systems must implement filtering workflows by group and name.

Example:

# Querying available workflows with group and name filter
workflows_result = WorkflowService.get_workflows(group='default', name='example')
if workflows_result['success']:
    workflow_handlers = workflows_result['data']['workflows']

Executing Workflows

Workflow handlers are self-contained triggers for a specific workflow in a given system. The WorkflowHandler.run method allows performing a workflow run with a given payload. Depending on the system, workflow runs can be synchronous and return the result of the workflow or asynchronous and return necessary information to check the workflow status in a given workflow system.

Example:

# Executing a workflow with a payload
payload = { ... }
result = handler.run(payload)

OpenIMIS Backend Payment Cycle Reference Module Documentation

Introduction

The OpenIMIS Backend Payment Cycle Reference Module is a crucial component of the OpenIMIS system. This module is designed to handle payment cycles and facilitate periodical payments for various business objects connected to payment plans. It offers services and functionalities to perform payment cycle calculations, including a specific service customized for Benefit Plan payment cycle calculation.

ORM Mapping

The Payment Cycle Reference Module utilizes ORM mapping to interact with the underlying database. The following mappings are used:

• payment_cycle_paymentcycle, payment_cycle_historicalpaymentcycle -> Individual: Represents the payment cycle entity.

Developers can use this mapping to access payment cycle data efficiently.

GraphQL Queries

The module provides a GraphQL query to retrieve payment cycle information:

• paymentCycle: Retrieves payment cycle data based on specified criteria.

GraphQL queries offer a flexible and efficient way to fetch relevant payment cycle information.

GraphQL Mutations

The module offers a GraphQL mutation to trigger the calculation of payment cycles:

• processBenefitPlanPaymentCycle: Initiates the calculation process for Benefit Plan payment cycles.

GraphQL mutations allow seamless execution of payment cycle calculations within the OpenIMIS system.

Services

The Payment Cycle Reference Module provides the following services:

• PaymentCycleService: A generic service containing the workflow for payment cycle calculation.

• BenefitPlanPaymentCycleService: A service customized for Benefit Plan payment cycle calculation.

Developers can utilize these services to perform payment cycle calculations and retrieve the results efficiently.

Configuration Options

The behavior of the Payment Cycle Reference Module can be customized through configuration options, which can be modified via core.ModuleConfiguration. The available configuration options are:

• gql_query_payment_cycle_perms: Specifies the required rights to query PaymentCycle. (Default: ["200001"])

• gql_create_payment_cycle_perms: Specifies the required rights to create PaymentCycle. (Default: ["200002"])

• gql_update_payment_cycle_perms: Specifies the required rights to update PaymentCycle. (Default: ["200003"])

• gql_delete_payment_cycle_perms: Specifies the required rights to delete PaymentCycle. (Default: ["200004"])

• gql_mutation_process_payment_cycle_perms: Specifies the required rights to call the processBenefitPlanPaymentCycle GraphQL Mutation. (Default: ["200005"])

These options allow administrators to control access and permissions related to payment cycle data and calculations.

Dependencies

The Payment Cycle Reference Module relies on the following modules:

• core: Provides core functionality and utilities for the OpenIMIS system.

• social_protection: Manages social protection-related information within the OpenIMIS system.

• contribution_plan: Handles contribution plan data.

• calculation: Facilitates calculation-related functionalities within the OpenIMIS system.

Ensure that these modules are correctly installed and configured for the Payment Cycle Reference Module to function correctly.

Payment Cycle Service

The Payment Cycle Service specifies a generic workflow for performing payment cycle calculations for various business objects connected to payment plans. It includes a specialized service for Benefit Plan objects. To trigger a calculation, the service requires a user reference, year, and month. Additional keyword arguments can be passed to the process() method to be used in calculations.

Example usage:

result = BenefitPlanPaymentCycleService(user).process(year=year, month=month)

The result is a dictionary containing the status of the operation, indicating whether it completed successfully or encountered errors. It also includes messages and details of any errors that occurred during the calculation. Additional data returned from specific implementations of services and calculation rules are grouped by the ID of the main queryset entry (BenefitPlan ID in this case).

Please note that this documentation provides an overview of the features and components of the Payment Cycle Reference Module. For detailed information on how to set up, configure, and use the module, refer to the specific documentation and guidelines provided in the codebase and related resources. Additionally, the documentation is subject to updates and improvements as the module evolves, so make sure to keep it up-to-date with any changes you make.

OpenIMIS Backend Calcrule_Social_Protection Reference Module Documentation

Introduction

The OpenIMIS Backend Calcrule_Social_Protection Reference Module is a critical component of the OpenIMIS system. This module is responsible for performing calculations to determine the amount of payment for beneficiaries based on specific criteria specified in custom filters of payment plans. It allows for flexible and customized payment calculations tailored to the needs of social protection programs.

Calculation Process

The calculation process in the Calcrule_Social_Protection module is crucial in determining the payment amount for beneficiaries. The calculation is performed based on the specific criteria defined in the custom filters associated with the payment plan.

Custom Filters

Custom filters play a pivotal role in the calculation process. They are user-defined criteria that determine how the payment amount is calculated for each beneficiary. The custom filters are configured within the payment plan and are tailored to the requirements of the social protection program.