Contract

Detailed description of configuring the contract service

Overview

The contract service provides the functionality of a works contract.

The source code for this service is available here. Refer to the below docs for a deeper understanding of this service.

Low-level design

Functional specifications

Pre-requisites

A running DIGIT platform is needed to deploy the contract service. Specifically, the following dependencies are needed:

• Estimate

• Organisation

• User

• Workflow

• IDGen

• HRMS

• Notification

• Persister

• Indexer

• MDMS

Functionality

This service provides APIs to create, update and search for contracts. Refer to the functional specifications here for detailed scope and functionality. Low-level technical design is available here.

Deployment

The below variables should be configured for the contract service in the Helm environment file before deployment. The Helm environment file will be located under:

https://github.com/{{ORG}}/DIGIT-DevOps/deploy-as-code/helm/environments/{{EnvironmentFile}}.yaml

Refer to the sample here.

• Add db-host,db-name,db-url,domain and all the digit core platform services configurations (Idgen, workflow,user etc.) in the YAML file.

• Add contract-service related environment variables’ value like the way it's done in ‘dev’ environment YAML file. Search for "contract-service" in the file.
• Add the ‘egov-mdms-service’ related configuration to the respective environment YAML file. Make sure you change the gitsync.branch name.
• Check the contract-service persister file is added to the egov-persister.perister-yml-path variable. If not, please add the way it's done here.
• Make sure to add the DB(Postgres and flyway) username & password in the respective environment secret yaml file. Follow the steps here.
• Make sure to add the DIGIT core services-related secrets configured in the respective environment secret file. Follow the steps here.

Restart egov-mdms-service, egov-persister, egov-indexer, inbox, egov-workflow-v2, egov-accesscontrol and zuul after the above changes are performed.

Configuration

MDMS Configuration

Configure actions, roles and role-action mappings from the table below. Follow the steps here.

Role	APIs
WORK_ORDER_CREATOR	/contract/v1/_create
	/contract/v1/_update
	/contract/v1/_search
	/wms/contract/_search
WORK_ORDER_VERIFIER	/contract/v1/_update
	/contract/v1/_search
	/wms/contract/_search
WORK_ORDER_APPROVER	/contract/v1/_update
	/contract/v1/_search
WORK_ORDER_VIEWER	/contract/v1/_search
	/wms/contract/_search
EMPLOYEE_COMMON	/inbox/v2/_search

These must be translated into JSON in the role-action mapping module in MDMS.

Example - available here.

Contract masters

The following masters are to be added as per the table below:

CBO Roles	https://github.com/egovernments/egov-mdms-data/blob/0dd049ffddbc7c6078b940b5eb9eb4951eb8996a/data/pg/works/ContractCBORoles.json
OCI Roles	https://github.com/egovernments/egov-mdms-data/blob/0dd049ffddbc7c6078b940b5eb9eb4951eb8996a/data/pg/works/ContractOfficerIncharge.json
ContractType	https://github.com/egovernments/egov-mdms-data/blob/0dd049ffddbc7c6078b940b5eb9eb4951eb8996a/data/pg/works/ContractType.json
Overheads	https://github.com/egovernments/egov-mdms-data/blob/0dd049ffddbc7c6078b940b5eb9eb4951eb8996a/data/pg/works/Overheads.json

Idgen Configuration

Make sure the id format is configured in the ‘IdFormat.json’ file of the ‘common-masters’ module. The sample is available here.

IDGen Format
{ "format": "WO/[fy:yyyy-yy]/[SEQ_CONTRACT_NUM]", "idname": "contract.number" } { "format": "RW/[fy:yyyy-yy]/[SEQ_CONT_SUPPLEMENT_NUM]", "idname": "contract.supplement.number" }

Workflow Configuration

Contract Workflow

The following workflow JSON needs to be put in the request body of the /egov-workflow-v2/egov-wf/businessservice/_create API.

For more information on configuring workflow, please refer to the Workflow Service documentation here.

"BusinessServices": [
    {
      "tenantId": "pg",
      "businessService": "CONTRACT",
      "business": "contract-service",
      "businessServiceSla": 604800000,
      "states": [
        {
          "sla": null,
          "state": null,
          "applicationStatus": null,
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "CREATE",
              "nextState": "PENDING_FOR_VERIFICATION",
              "roles": [
                "WORK_ORDER_CREATOR"
              ]
            }
          ]
        },
        {
          "sla": 172800000,
          "state": "PENDING_FOR_VERIFICATION",
          "applicationStatus": "SUBMITTED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "VERIFY_AND_FORWARD",
              "nextState": "PENDING_FOR_APPROVAL",
              "roles": [
                "WORK_ORDER_VERIFIER"
              ]
            },
            {
              "action": "SEND_BACK",
              "nextState": "PENDING_FOR_CORRECTION",
              "roles": [
                "WORK_ORDER_VERIFIER"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "WORK_ORDER_VERIFIER"
              ]
            }
          ]
        },
        {
          "sla": 86400000,
          "state": "PENDING_FOR_APPROVAL",
          "applicationStatus": "VERIFIED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "APPROVE",
              "nextState": "APPROVED",
              "roles": [
                "WORK_ORDER_APPROVER"
              ]
            },
            {
              "action": "SEND_BACK",
              "nextState": "PENDING_FOR_VERIFICATION",
              "roles": [
                "WORK_ORDER_APPROVER"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "WORK_ORDER_APPROVER"
              ]
            },
            {
              "action": "SEND_BACK_TO_ORIGINATOR",
              "nextState": "PENDING_FOR_CORRECTION",
              "roles": [
                "WORK_ORDER_APPROVER"
              ]
            }
          ]
        },
        {
          "sla": 604800000,
          "state": "APPROVED",
          "applicationStatus": "APPROVED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "ACCEPT",
              "nextState": "ACCEPTED",
              "roles": [
                "ORG_ADMIN"
              ]
            },
            {
              "action": "DECLINE",
              "nextState": "PENDING_FOR_REASSIGNMENT",
              "roles": [
                "ORG_ADMIN"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "ORG_ADMIN"
              ]
            }
          ]
        },
        {
          "sla": 86400000,
          "state": "PENDING_FOR_CORRECTION",
          "applicationStatus": "SENT_BACK",
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "EDIT",
              "nextState": "PENDING_FOR_VERIFICATION",
              "roles": [
                "WORK_ORDER_CREATOR"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "WORK_ORDER_CREATOR"
              ]
            }
          ]
        },
        {
          "sla": 86400000,
          "state": "PENDING_FOR_REASSIGNMENT",
          "applicationStatus": "DECLINED",
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "EDIT",
              "nextState": "PENDING_FOR_VERIFICATION",
              "roles": [
                "WORK_ORDER_CREATOR"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "WORK_ORDER_CREATOR"
              ]
            }
          ]
        },
        {
          "sla": null,
          "state": "ACCEPTED",
          "applicationStatus": "ACCEPTED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "isStateUpdatable": false,
          "actions": [
          ]
        },
        {
          "sla": null,
          "state": "REJECTED",
          "applicationStatus": "REJECTED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "isStateUpdatable": false,
          "actions": [
          ]
        }
      ]
    }
  ]

Persister Configuration

Please make sure that the file contract-service-persister.yml is present in the configs repository in the below location.

https://github.com/<YOUR ORGANISATION>/works-configs/tree/DEV/egov-persister

If not present, please make sure to add the persister YML file.

Make sure to restart MDMS and the persister service after adding the file at the above location.

Indexer Configuration

Please make sure that the file contractservices-indexer.yml is present in the configs repository in the below location.

https://github.com/{{your organisation}}/works-configs/tree/DEV/egov-indexer

Inbox Configuration

In the MDMS repository, locate the inbox configuration file. Make sure the following JSON is added to the inbox configuration:

{
  "module": "contract-service",
  "index": "contract-inbox",
  "allowedSearchCriteria": [
    {
      "name": "tenantId",
      "path": "Data.tenantId.keyword",
      "isMandatory": true,
      "operator": "EQUAL"
    },
    {
      "name": "workOrderNumber",
      "path": "Data.contractNumber.keyword",
      "isMandatory": false,
      "operator": "EQUAL"
    },
    {
      "name": "revisedWorkOrderNumber",
      "path": "Data.supplementNumber.keyword",
      "isMandatory": false,
      "operator": "EQUAL"
    },
    {
      "name": "status",
      "path": "Data.currentProcessInstance.state.uuid.keyword",
      "isMandatory": false
    },
    {
      "name": "projectId",
      "path": "Data.additionalDetails.projectId.keyword",
      "isMandatory": false,
      "operator": "EQUAL"
    },
    {
      "name": "projectType",
      "path": "Data.additionalDetails.projectType.keyword",
      "isMandatory": false,
      "operator": "EQUAL"
    },
    {
      "name": "ward",
      "path": "Data.additionalDetails.ward.keyword",
      "isMandatory": false,
      "operator": "EQUAL"
    },
    {
      "name": "locality",
      "path": "Data.additionalDetails.locality.keyword",
      "isMandatory": false,
      "operator": "EQUAL"
    },
    {
      "name": "wfStatus",
      "path": "Data.contractStatus.keyword",
      "isMandatory": false
    },
    {
      "name": "assignee",
      "path": "Data.currentProcessInstance.assignes.uuid.keyword",
      "isMandatory": false
    }
  ],
  "sortBy": {
    "path": "Data.auditDetails.createdTime",
    "defaultOrder": "DESC"
  },
  "sourceFilterPathList": [
    "Data.contractNumber",
    "Data.businessService",
    "Data.additionalDetails.projectName",
    "Data.additionalDetails.projectId",
    "Data.additionalDetails.orgName",
    "Data.currentProcessInstance",
    "Data.totalContractedAmount",
    "Data.auditDetails"
  ]
}

Restart the Inbox service after updating the above configuration

Integration

The API specifications for this service are located here. Postman scripts are available here for reference to understand the request payloads.