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 payroll 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 payroll 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 payroll management.

Configuration Options

The behavior of the Payroll 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 Payrol 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 Payroll Reference Module to function properly.