BPM with Camunda Workflows
Below are the various topics/details are documented in this confluence page which provide more technical details on developing the approval process workflows using Camunda BPM tool to approve the customer and contact create and update requests on Azure cloud platform.
1. Environment Setup
Download camunda-modeler-4.12.0-win-x64 and extract it. This will be used to develop the Camunda workflow. Once the workflow is developed, it needs to deployed to Spring boot based runtime environment which run on built in Tomcat server.
Below is the project base which provides the runtime environment based on spring boot and runs on Tomact server. Download the below project to develop/enhance the CMD customer approval workflow.
Maersk-Global/smds-cmd-workflow-service at develop (github.com)
Below are 3 major components of Camunda environment setup.
Camunda Admin page:
Admin is an application that allows you to configure users and groups via the engine’s Identity Service and authorizations via the engine’s Authorization Service. Below is the URL to access admin console.
http://localhost:8080/camunda/app/admin/.
Camunda cockpit page:
Cockpit is a web based application used for monitoring and operations. It provides access to deployed BPMN processes and DMN decisions, allows searching through running and ended instances and performing operations on them. You could access the Cockpit using the below URL:
http://localhost:8080/camunda/app/cockpit/default/#/dashboard
Camunda modeler:
Camunda Modeler is a desktop application that is used for modeling BPMN. It allows you to model files directly on your local file system.
2. Existing Customer & Contact Workflow functionality
In current system the Customer workflow will get triggered during below create scenarios.
- If Customer Address is not Validated then WF will get generate
- If user tries to create duplicate Customer then WF will get generate
- If Customer belongs to European Country and Tax is not validated as per Vies then WF will get generate.
- If user select Customer group type as SCPI Tax Exempted while creating
- If Customer is detected as Internal Customer then WF gets generated.
In current system the Customer workflow will get triggered during below update scenarios.
- Trading Name Change
- If user tries to reactivate the customer i.e status change from Suspend to Active
- If user select Customer group type as SCPI Tax Exempted
- User Updates Address and if it is not Validated
- User Updates Customer details and found duplicates and still proceeds further with duplicate creation
- User Changes Existing Tax Number or Adds Tax against EU Country for which VIES tax validation fails
Below are the different types of workflow created based on the scenarios (Create/Update) mentioned above.
- Suspend-To-Active
- Address-Override
- Duplicate-Override
- VIES-Validation-Failed
- Trading-Name-Change
- Tax-Change
- Account-Group-Change
- Customer-Group-Change (SCPI-Tax-Exempted)
- Reactivate
- BVD_TRADING_NAME_CHANGE - "Bvd-Trading Name Change"
- BVD_ACTIVE_INSOLVENCY_PROCEEDINGS - "Bvd-Active (insolvency proceedings)"
- BVD_BANKRUPTCY - "Bvd-Bankruptcy"
- BVD_IN_LIQUIDATION - "Bvd-In liquidation"
- BVD_DISSOLVED_STATUS - "Bvd-Dissolved"
- BVD_DISSOLVED_MERGER_OR_TAKE_OVER - "Bvd-Dissolved (merger or take-over)"
- BVD_DISSOLVED_DEMERGER - "Bvd-Dissolved (demerger)"
- BVD_DISSOLVED_BANKRUPTCY - "Bvd-Dissolved (bankruptcy)"
- BVD_DISSOLVED_LIQUIDATION - "Bvd-Dissolved (liquidation)"
- BVD_INACTIVE_NO_PRECISION - "Bvd-Inactive (no precision)"
- BVD_STATUS_UNKNOWN - "Bvd-Status unknown"
Below is the existing contact workflow functionality.
This will be triggered when user create new customer along with Contact.
This workflow will keep on checking for Customer record whether it is approved or rejected.
- If customer record rejected then Contact record deleted.
- If customer record approved then contact will get activated and it will be published
The below query is used to get the role which will be passed to workflow when triggering from UpsertCustomer service.
- To get the respective role based on Country. This MDM_ROLE will be retrieved by upsertCustomer service and passed to AVOS. WITH COUNTRY_CODE_DETAILS AS ( SELECT DISTINCT CNTRY_NM.ROWID_OBJECT COUNTRY_MDM_ID, CNTRY_NM.NAME COUNTRY_NAME, CNTRY_CODE.CODE COUNTRY_CODE FROM C_ALT_CODE CNTRY_CODE, C_GDA_DFND_AREA CNTRY_NM WHERE CNTRY_CODE.GDA_DFND_AREA_ROWID = CNTRY_NM.ROWID_OBJECT AND CNTRY_NM.TYP_TYPE_CD = 'GDA.COUNTRY' AND CNTRY_NM.ACTIVE_FLAG = 'Y' AND CNTRY_CODE.TYP_TYPE_ROWID = ( SELECT ROWID_OBJECT FROM C_TYP_TYPE WHERE CODE = 'ALT_CODE.RKST' ) AND ( CNTRY_CODE.CODE = ? ) ) SELECT COUNTRY_CODE_DETAILS.COUNTRY_CODE, C_ALT_CODE.CODE CLUSTER_CODE, CLUSTER_NAME.NAME CLUSTER_NAME, CONCAT('CMD_', C_ALT_CODE.CODE) MDM_ROLE FROM COUNTRY_CODE_DETAILS INNER JOIN C_GDA_DFND_AREA_REL ON C_GDA_DFND_AREA_REL.GDA_DFND_AREA_CHLD_ROWID = COUNTRY_CODE_DETAILS.COUNTRY_MDM_ID INNER JOIN C_GDA_DFND_AREA CLUSTER_NAME ON C_GDA_DFND_AREA_REL.GDA_DFND_AREA_PRNT_ROWID = CLUSTER_NAME.ROWID_OBJECT INNER JOIN C_GDA_BDA CLUSTER_INFO ON CLUSTER_INFO.GDA_DFND_AREA_ROWID = CLUSTER_NAME.ROWID_OBJECT INNER JOIN C_ALT_CODE ON C_ALT_CODE.GDA_DFND_AREA_ROWID = CLUSTER_NAME.ROWID_OBJECT WHERE C_GDA_DFND_AREA_REL.HUB_STATE_IND = 1 AND CLUSTER_NAME.ACTIVE_FLAG = 'Y' AND CLUSTER_INFO.BDA_TYPE_CD = 'CLUSTER' AND C_ALT_CODE.TYP_TYPE_ROWID = ( SELECT ROWID_OBJECT FROM C_TYP_TYPE WHERE CODE = 'ALT_CODE.BDACODE' )
3. Camunda Workflow design
Below is the process flow diagram for customer approval in case of create or update scenarios.
UpsertCustomer service need to trigger customer workflow in below create scenarios:
- If Customer Address is not Validated then “Address-Override” WF needs to be triggered
- If user tries to create duplicate Customer then “Duplicate-Override” WF needs to be triggered
- If Customer belongs to European Country and Tax is not validated as per Vies then “VIES-Validation-Failed” WF needs to be triggered.
- If user select Customer group type as SCPI Tax Exempted while creating then “Customer-Group-Change” WF needs to be triggered
- If Customer is detected as Internal Customer then “Account-Group-Change“ WF needs to be triggered.
- If customer get created using the BVD source then
- If trading name change then “Bvd-Trading Name Change” WF needs to be triggered
- If the BVD customer status is ‘Active (insolvency proceedings)’ then “Bvd-Active (insolvency proceedings)” WF needs to be triggered.
- If the BVD customer status is ‘Bankruptcy’ then “Bvd-Bankruptcy” WF needs to be triggered
- If the BVD customer status is ‘In liquidation’ then “Bvd-In liquidation” WF needs to be triggered
- If the BVD customer status is ‘Dissolved’ then “Bvd-Dissolved” WF needs to be triggered
- If the BVD customer status is ‘Dissolved (merger or take-over)’ then “Bvd-Dissolved (merger or take-over)” WF needs to be triggered
- If the BVD customer status is ‘Dissolved (demerger)’ then “Bvd-Dissolved (demerger)” WF needs to be triggered
- If the BVD customer status is ‘Dissolved (bankruptcy)’ then “Bvd-Dissolved (bankruptcy)” WF needs to be triggered
- If the BVD customer status is ‘Dissolved (liquidation)’ then “Bvd-Dissolved (liquidation)” WF needs to be triggered
- If the BVD customer status is ‘Inactive (no precision)’ then “Bvd-Inactive (no precision)” WF needs to be triggered
- If the BVD customer status is ‘Status unknown’ then “Bvd-Status unknown” WF needs to be triggered
- Customer along with contact also can be created. In this case based on above condition respective customer workflow will be triggered. During review process user/Datasteward should be able to see the customer and contact details under that customer.
UpsertCustomer service need to trigger customer workflow in below update scenarios:
- If customer Trading Name Changed then “Trading Name Change” WF needs to be triggered.
- If user tries to reactivate the customer i.e status change from Suspend to Active then “Suspend-To-Active” WF needs to be triggered
- If user select Customer group type as SCPI Tax Exempted then “Customer-Group-Change” WF needs to be triggered
- User Updates Address and if it is not Validated then “Address-Override” WF needs to be triggered
- User Updates Customer details and found duplicates and still proceeds further with duplicate creation then “Duplicate-Override“ WF needs to be triggered
- User Changes Existing Tax Number then “Tax-Change“ WF needs to be triggered
- If user adds Tax against EU Country for which VIES tax validation fails then “VIES-Validation-Failed“ WF needs to be triggered
Below is the input payload structure needs to be passed from UpsertCustomer service when WF is triggered.
{
"variables":
{
"requestType" : {"value":"Create","type":"string"},
"requesterId" : {"[value":"seenu.rvce@gmail.com](mailto:value%22:%22krvarma08@gmail.com)","type":"string"},
"customerCode" : {"value":"IN02738845","type":"string"},
"contactCode" : {"value":"IN04567832","type":"string"},
"ADSRole" : {"value":"CMD\_IBC","type":"string"},
"financeRole" : {"value":"CMDFinance","type":"string"},
"workflowIndicator" : {"value":"DUPLICATE|TRADING\_NAME\_CHANGE","type":"string"},
"sourceSystemName" : {"value":"HSUD","type":"string"},
“autoApproveSystem” : {“value”:”HSUD”, “type”:”string”}
}
}
Based on Country name/code then role needs to be determined in UpsertCustomer and the identified role needs to be passed.
Below table give more details on each field in the input payload.
| Field Name | Description | Sample Value |
|---|---|---|
| requestType | This field indicates the type of request which is either Create or Update | Create or Update |
| requesterId | This is email id of request submitter which will be used for audit purpose. | any valid Maersk email id |
| customerCode | This is CMD customer code which will be used for getting complete information about customer. | IN02738845 |
| contactCode | This is CMD contact code which will be used for getting complete information about contact. | IN04567832 |
| ADSRole | This is Area Data Steward role or cluster role to which the task need to be assigned for his/her action. ADS can either approve or reject the request. | CMD Super User, CMDAccountGroupManager, CMDConcernCodeManager, CMDCustFacilityManager, CMDDataQualityAssurance, CMDGlobalBusinessAdministrator, CMDHierarchyManager, CMDOnBehalfOfRoleCMDReadOnly, CMDRegulatoryComplianceTeam, CMDSegmentationManager,CMDVipRole, CMDWebBLManager, CMDY_ADMIN, CMD_AEC, CMD_CAD, CMD_CAR, CMD_CIC, CMD_CME, CMD_CWA, CMD_EAF, CMD_EEC, CMD_EME, CMD_ESA, CMD_FRC, CMD_GBC, CMD_GCC, CMD_GEO_CTY_ROLE, CMD_GEO_CTY_ROLE_ReadOnly, CMD_HAE, CMD_IBC, CMD_IDP, CMD_MIC, CMD_NEA ,CMD_NOA, CMD_NWA, CMD_NWC, CMD_OCC, CMD_PKC, CMD_SAC, CMD_SAI, CMD_SAS, CMD_SCA, CMD_SWA, CMD_SWE, CMD_TMS, CMD_VCM, CMD_WME, CMD_WSA |
| financeRole | This is the role name required for finance approval. | CMDFinance |
| workflowIndicator | This indicates what type of workflow it is. What the reason the workflow triggered. | SUSPEND_TO_ACTIVEADDRESS_OVERRIDEDUPLICATETRADING_NAME_CHANGEVIES_VALIDATION_FAILEDTAX_CHANGEACC_GROUP_CHANGECUST_GROUP_CHANGEREACTIVATEBVD_TRADING_NAME_CHANGEBVD_ACTIVE_INSOLVENCY_PROCEEDINGSBVD_BANKRUPTCYBVD_IN_LIQUIDATIONBVD_DISSOLVED_STATUSBVD_DISSOLVED_MERGER_OR_TAKE_OVERBVD_DISSOLVED_DEMERGERBVD_DISSOLVED_BANKRUPTCYBVD_DISSOLVED_LIQUIDATIONBVD_INACTIVE_NO_PRECISIONBVD_STATUS_UNKNOWN |
| sourceSystemName | This indicate what source system requested to create or update record. | PRTL, HSUD, SAP, SFDC |
| autoApproveSystem | This indicate whether the request should go for approval process or auto approved. This will help for systems for which initially they need auto approve and later they can change to approval process required. | Yes, No |
When customer create/update request is submitted, the upsertCustomer service need to do below activities:
- The records needs to be created in the respective tables and the record state should be in pending
- Authenticate the user in AD and get the roles he belongs to.
- Determine the ADS role based on country from C_ALT_CODE, C_GDA_DFND_AREA, C_GDA_BDA, C_GDA_DFND_AREA_REL tables.
- Derive the workflowIndicator and source system name
- Prepare the input payload to trigger the customer workflow
- Based on the workflow trigger condition discussed in above section, trigger workflow if condition is met if not no need to trigger workflow.
- During the approval process, if user try to update record from UI it should not allow any updates (there should be lock on that customer record).
4. List of APIs required
| Sl.No | API | In/Out Parameters | Details |
|---|---|---|---|
| 1 | PromoteRecords | In: CustomerCode ContactCodeOut: result (true/false) | When user approve the task from UI, this API will be triggered from Camunda by passing CustomerCode. Based on Customer code promote/update the record status to active in all respective tables. When the record is promoting the new values need to be updated in the base tables. The contact record also will be promoted in case contact is onboarded along with customer. |
| 2 | Update Valid Through Date to current date in relationship table. | In: CustomerCodeOut: result (true/false) | When master-duplicate relationship will be removed by user, the reuqest will go for approavl process. Once it is approved the valid through date in relationship table to current date to break it. |
| 3 | Update customer table CUSTOMER_GROUP_TYPE field to either Internal or External (ZEXC) | In: CustomerCode, GroupTypeOut: result (true/false) | Once Finance approver approves the request, this API will be used to mark the customer as Internal Customer if Finance approver approves else External customer if Finance approver rejects it. |
| 4 | Call Publish customer (EMP & MQ) services | In: CustomerCode,ContactCodeOut: result (true/false) | Call the cloud EMP publish API after records become active to publish customer/contact to EMP topic based on CustomerCode/ContactCode.Once the message is published to EMP on cloud, EMP will replicate cloud message to on-prem. On on-prem platform will convert JSON message to XML and publish to MQ for MQ consumers. |
| 5 | Delete the customer/Contact records | In: CustomerCodeOut: result (true/false) | Incase of CREATE scenario: When user reject the task from UI, this API will be triggered from Camunda by passing CustomerCode. Based on Customer code delete the records from the respective core tables for customer and contact.In case of UPDATE scenario: When the record is deleting the new values need to be deleted from CUSTOMER_WF_PROCESS_DETAILS table for customer. |
| 6 | Create task |
Where customizations are required that needs to be handled in backend services.
Below are the roles with access details.
| Sl.No | Role Name | Access details |
|---|---|---|
| 1 | CMD Super User | Allows all customer edits. CDG Team need this role access. |
| CMDCustFacilityManager | ||
| 2 | CMDDataQualityAssurance | |
| 3 | CMDGlobalBusinessAdministrator | |
| 4 | CMDHierarchyManager | |
| 5 | CMDOnBehalfOfRole | |
| 6 | CMDReadOnly | |
| 7 | CMDRegulatoryComplianceTeam | |
| 8 | CMDSegmentationManager | |
| 9 | CMDVipRole | |
| 10 | CMDWebBLManager | |
| 11 | CMDY_ADMIN | |
| 12 | CMD_AEC | |
| 13 | CMD_CAD | |
| 14 | CMD_CAR | |
| 15 | CMD_CIC | |
| 16 | CMD_CME | |
| 17 | CMD_CWA | |
| 18 | CMD_EAF | |
| 19 | CMD_EEC | |
| 20 | CMD_EME | |
| 21 | CMD_ESA | |
| 22 | CMD_FRC | |
| 23 | CMD_GBC | |
| 24 | CMD_GCC | |
| 25 | CMD_GEO_CTY_ROLE | |
| 26 | CMD_GEO_CTY_ROLE_ReadOnly | |
| 27 | CMD_HAE | |
| 28 | CMD_IBC | |
| 29 | CMD_IDP | |
| 30 | CMD_MIC | |
| 31 | CMD_NEA | |
| 32 | CMD_NOA | |
| 33 | CMD_NWA | |
| 34 | CMD_NWC | |
| 35 | CMD_OCC | |
| 36 | CMD_PKC | |
| 37 | CMD_SAC | |
| 38 | CMD_SAI | |
| 39 | CMD_SAS | |
| 40 | CMD_SCA | |
| 41 | CMD_SWA | |
| 42 | CMD_SWE | |
| 43 | CMD_TMS | |
| 44 | CMD_VCM | |
| 45 | CMD_WME | |
| 46 | CMD_WSA |
5. Active Directory Integration
We need to integrate with Active Directory to get the roles and user details and to assign the tasks respectively.
Below points needs to be considered while integrating with AD
- User need to login to Customer portal using AD authentication
- While triggering the Customer workflow form upsertCustomer API, upsertCustomer need to check user and role details in AD and pass the details in payload.
- In the task inbox in CMD portal, make sure the roles against the logged in user needs to be validated and task needs to be displayed accordingly (UI work)
- While approving task, first task needs to be claimed against that user and then execute approval action. (this step is not required to be claimed by user because the user already authenticated with AD)
6. Camunda workflow, CMD and UI (CMD Portal) integration
The below diagram shows the interaction between CMD, Camunda WF, CMD Portal, Active directory and BPM Database.
7. Database and Tables for Workflows
8. API Path for Camunda Service:
API Path for Camunda Service is,
/global-mdm/customers/workflows
9. Camunda Service Request Details for CMD UI:
| Endpoint | Input Param | Method Type | Description |
|---|---|---|---|
| /global-mdm/customers/workflows/tasks/deployment | MultipartFile | POST | Deploy the BPMN file to Camunda moduler |
| /global-mdm/customers/workflows/tasks/process/start | startRequest | POST | Trigger the workflow from Ingest customer |
| /global-mdm/customers/workflows/tasks | groups,owner,taskId,searchApiRequest | GET | By default we will fetch list of tasks based on groups.If approver didn’t find the details he will use search and filter the tasks based searchApiRequest |
| /global-mdm/customers/workflows/tasks/{taskId}/{processId} | taskId and processId | GET | Retrieve the Existing customer details from ElasticSearch based on customer code and Get Current WorkflowCustomer details from customer_wf_process_detail table |
| /global-mdm/customers/workflows/tasks/claim | taskId,processId,userApmId,claimstatus | POST | If any approver wants to review the workflow and approve/reject first he needs to claim the task |
| /global-mdm/customers/workflows/tasks/comment | taskId and comment | POST | Add the comments to the task |
| /global-mdm/customers/workflows/tasks/complete | taskId,processId,userApmId,claimstatus | POST | approve/reject the workflow |
| /global-mdm/customers/workflows/tasks/process/{processId} | processId | GET | Get workflow details based on the processId |
| /global-mdm/customers/workflows/tasks/history/process/{processId} | processId | GET | Get full workflow history details based on processId |
10. Deployment of Workflows
There are ways to deploy the camunda workflow (.bpm) file.
- When server gets started, it will identify the workflows from configuration file .bpmn under resources folder.
- From Camunda modeler itself can be deployed.
- Provide the server details where the workflow (.bpmn) needs to be deployed.
- Deployment Name : Customer_Workflow
- REST Endpoint: http://localhost:8080/engine-rest
- Deploy from InteliJ itself
- Provide the server details where the workflow (.bpmn) needs to be deployed.
- Once deployed test the workflow by hitting the below URL from postman
Was this page helpful?