openimis-be-payroll_py

ORM Mapping

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

payroll_payroll, payroll_historicalpayroll -> Payroll: Represents a payroll entity.
payroll_paymentpoint, payroll_historicalpaymentpoint -> PaymentPoint: Represents the payment point. Associated with payment point manager user and location.
payroll_payrollbill, payroll_historicalpayrollbill → PayrollBill: Represents the relation between invoice and the payroll.
payroll_benefitconsumption, payroll_historicalbenefitconsumption-> BenefitConsumption: Represents the consumption of the benefit.
payroll_benefitattachment, payroll_historicalbenefitattachment → BenefitAttachment: Represents association between Bill and BenefitConsumption
payroll_benefitconsumption, payroll_historicalbenefitconsumption → PayrollBenefitConsumption: Represents the relation between Payroll and the BenefitConsumption
payroll_csvreconciliationupload, payroll_historicalcsvreconciliationupload → CsvReconciliationUpload: Represents the reconciliation of the payroll based on the csv file upload.

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

GraphQL Queries

The module provides several GraphQL queries to retrieve individual and group-related information:

paymentPoint: Retrieves payment points.
payroll Retrieves payroll information based on specified criteria.
billByPayroll: Retrieves bills information based on specified criteria.
benefitConsumption: Retrieves benefit consumption based on specified criteria.
paymentMethods: Retrieves payment methods based on specified criteria.
paymentGatewayConfig: Retrieves payment gateway config based on specified criteria.
benefitAttachmentByPayroll: Retrieves consumption attachments based on specified criteria.
csvReconciliationUpload: Retrieves CSV Reconciliation uploads based on specified criteria.
payrollBenefitConsumption: Retrieves benefit consumptions based on specified criteria.
benefitsSummary: Retrieves benefit summary based on the specified criteria.

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

GraphQL Mutations

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

List of available mutations:

create_payment_point
update_payment_point
delete_payment_point
create_payroll
delete_payroll
close_payroll
reject_payroll
make_payment_for_payroll
delete_benefit_consumption

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

Services

The module provides the following services:

PaymentPointService: Provides create, update, delete operations for the Payment Point
PayrollService: Provides methods to create, update, delete, create attachments, approve and reject Payrolls.
BenefitConsumptionService: Offers methods to create, update, and delete BenefitConsumptions and it’s attachments.
CsvReconciliationService: Provides methods to download and upload of the Reconciliation files.

Developers can interact with these services to perform various operations related to individual and group management.

Configuration Options

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

Role Rights
gql_payment_point_search_perms, default: ["201001"],
gql_payment_point_create_perms, default: ["201002"],
gql_payment_point_update_perms, default: ["201003"],
gql_payment_point_delete_perms, default: ["201004"],
gql_payroll_search_perms, default: ["202001"],
gql_payroll_create_perms, default: ["202002"],
gql_payroll_delete_perms, default: ["202004"],
gql_csv_reconciliation_search_perms, default: ["206001"],
gql_csv_reconciliation_create_perms, default: ["206002"],

Specify the required rights to call graphQL operations.
Events
payroll_accept_event, default: "payroll.accept_payroll",
payroll_reconciliation_event, default: "payroll.payroll_reconciliation",
payroll_delete_event, default: "payroll.payroll_delete",
benefit_delete_event, default: "payroll.benefit_delete",
payroll_reject_event, default: "payroll.payroll_reject",

Specify the name of the event that will be sent to the signal orchestration on certain operations.

csv_reconciliation_field_mapping: Specified the mapping between the reconciliation fields and ORM.
Default:

    "csv_reconciliation_field_mapping": {
        'payrollbenefitconsumption__payroll__name': 'Payroll Name',
        'payrollbenefitconsumption__payroll__status': 'Payroll Status',
        'individual__first_name': 'First Name',
        'individual__last_name': 'Last Name',
        'individual__dob': 'Date of Birth',
        'code': 'Code',
        'status': 'Status',
        'amount': 'Amount',
        'type': 'Type',
        'receipt': 'Receipt',
    },

Reconciliation Field Names:

"csv_reconciliation_status_column": "Status",
"csv_reconciliation_paid_extra_field": "Paid",
"csv_reconciliation_receipt_column": "receipt",
"csv_reconciliation_errors_column": "errors",
"csv_reconciliation_code_column": "code",
"csv_reconciliation_paid_yes": "Yes",
"csv_reconciliation_paid_no": "No",

Specifies the names of columns in the Reconcilaition CSV files.

Payment Gateway Config
Specifies the details for the payment gateway client.
gateway_base_url, default: "http://41.175.18.170:8070/api/mobile/v1/",
endpoint_payment, default: "mock/payment",
endpoint_reconciliation, default: "mock/reconciliation",
payment_gateway_api_key, default: os.getenv('PAYMENT_GATEWAY_API_KEY'),
payment_gateway_basic_auth_username, default: os.getenv('PAYMENT_GATEWAY_BASIC_AUTH_USERNAME'),
payment_gateway_basic_auth_password, default: os.getenv('PAYMENT_GATEWAY_BASIC_AUTH_PASSWORD'),
payment_gateway_timeout, default: 5,
payment_gateway_auth_type, default: "basic", # can be 'token' or 'basic'
payment_gateway_class, default: "payroll.payment_gateway.MockedPaymentGatewayConnector",
receipt_length, default: 8

Specifies the configuration for the gateway connection.

OpenIMIS Modules Dependencies

The Individual Reference Module relies on the following module:

core: Provides core functionality and utilities for the OpenIMIS system.
social_protection: Provides functionality and utilities for the General Social Protection models
individual: Base functionality for Individual/Group management.
contribution_plan: Functionality for the Payment Plan Definitions.
location: Provide locations handling.

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