Status and
Routing Maintenance
Copyright 2005, R. James Holton. All rights reserved.
The Status File -
Workflow
The Status file (i.e., Status.xml) is used to control workflow once the initial state of the the report have been set by the ProcessESSReport module. The Status file is used by the approval process, audit process and payment processes to control status changes to reports and to notify people of the report process.
The Status File allows you to:
1. Create a report status.
2. Map a status to the legacy tables
3. Specify a screen message for a status
4. Indicate who should be notified when a report is assigned this status
5. Indicate the notification message
6. Indicate the class used to promote or approve a report in this status
7. Indicate the new status of the approval/promotion or rejection
8. Specify a monetary limit for the approvers
9. Determine the number of levels down for approval display
10. Indicate if a duplicate signature is allowed at this status
11. indicate which fields are filed with the approver's personnel number and date
12. Indicate whether a user can edit the report or an auditor can delete the report
The table root element is broken down into sub-elements which are separate collections of report status elements. Each sub-element collection corresponds to a set of routing rules. The element name is the name of the routing rules. This name is tied to a department and allows for departments to have different routing rules. For example, one department may require two signatures and another may require only one. In practice, it is advisable to keep the number of rules to a minimum to avoid complexity.
There are certain elements that are only defined in the "default" set of routing rules. The default set must be defined and will be used in the event that a report cannot be matched. It is recommended that if the default set is desired for a department, that it be discreetly specified.
Each routing rule (i.e., report status) must be called a row and have a sequence specified. Here's an example:
<row sequence="1">
…
</row>
The follow elements must be present in the default element. The elements that are only found in the default element are noted.
§
status -
This is the ESS status of the routing step or rule. A report must always have a status that is
found in the default element. You can
create your own status, however, in the short term, you should have these stati defined: ST_NEW, ST_SUBMIT_ON, ST_SUBMIT_OFF,
ST_REVIEWED, ST_APP
§ translation - This is the legacy system of the ESS status. The current tables contain these status codes, which correspond to the above: A0, B1, C1, D1, E2, F0, F1, G3, G4, G5, H4, L4
§ screen (default only) - This is the textual screen message that is displayed on report selection lists for reports with this status.
§ notify - This is the ESS class that is used to identify who is notified when a report is assigned this status. Current classes are:
§ ess.ESSAccounting - always returns "account@adisoft-inc.com."
§ ess.ESSAdmin - gets the email address of the admin assigned to the reports department.
§ ess.ESSApprover - gets the email address from the manager in the reporters profile.
§ ess.ESSAuditor - gets the email address of the admin assigned to the reports department.
§ ess.ESSManager - gets the email address from the manager in the reporters profile.
§ ess.ESSManagerDepartSimple - gets the email of the person in the manager slot of the depart this report is charged to. If that does not meet the criteria, chains through the user.manager clomun.
§ ess.ESSManagerDepartment - gets the email of the person in the manager slot of the depart this report is charged to. If that does not meet the criteria, chains through the depart.manager clomun.
§ ess.ESSManagerUnlessXCharge - functions as ess.ESSManager, unless the report is being charged to a department different from the one specified in the user.depart column, in which case it functions like ess.ESSManagerDepartment
§ ess.ESSSubmitter - returns the email of the person who submitted the report.
§ notifymessage - text of the message to be sent to the person speficied in the above notify element. Supports the following macros in the :
§ $name$ - reporters name, used in 2nd approval, payment message, delinquent message
§ $voucher$ - central reference, used in 2nd approval, payment message, delinquent message
§ $pvoucher$ - submitter personal reference, used in 2nd approval, payment message, delinquent message
§ $amount$ - receipt amount, used in payment message, delinquent message
§ $date$ - report create date, used in payment message, delinquent message
§ $update$ - G/L post date, used in payment message, delinquent message
§ $status$ - report status (screen) , used in payment message, delinquent message
§ $approver$ - name of approver originally routed to, used in delinquent message
There are no macros for the initial notification message which is handled by the ProcessESSReport class and controlled by the STATE table and the rules.xml file.
§ approval - Indicates who can approve the report at this status.
§ Manager - Submitter's manager
§ Admin - Administrator in charged department record
§ AdminOrAuditor - Either admin or auditor
§ ManagerOrAdmin - Either manager or admin
§ DepartmentManager - Manger in the charged department record
§ ManagerUnlessXharge - Manager unless cross-charged then department manager
§ Auditor - Any person designated as an auditor
§ result - new status if report is approved
§ reject - new status if report is rejected or disapproved
§ limitrequired - If 'Yes' the approval module will check the approver's limit against the report amount.
§ leveladjustment - Number of extra levels to drill down into the database to generate the reports to approve list. Usually set to '0', but for second level approvals will be set to '1'.
§ duplicatesignerallowed - If 'Yes' will accept an approval for this status even if the person has already signed off on the report. Valuable when combined with reports requiring two signatures only if over a certain level.
§ updatesqlsigner - name of column to update with approver's personnel number
§ updatesqldate - name of column to update with the approval date.
§ usereditallowed (default only) - A 'Yes' indicates that the report may be resubmitted by the user.
§ auditremoveallowed (default only) - A 'Yes' indicates that an auditor may delete this report from the database.
§ randomsampleratio (default only) - runs the RANDOMSELECT action (see STATE table below) and will promote a report based on the returned result and the POSITIVE status and NEGATIVE status specified in the STATE table. The number specified here is the divisor and the dividend is one. Example if an '8' is specified the selection ratio will be 1:8, or 12.5% of the reports will return true.
§ ceolimit – No or amount
§ signwithoutlimit – Yes or No
ProcessESSReport -
The ProcessESSReport class is used to set the initial status of a report that has been submitted to the central database, resolve any conflicts with previously submitted versions of the report and the notify various parties of any actions required. There are two files/tables that control the behavior of the ProcessESSReport class.
The first is the STATE table. (Note: The STATE table has been designated to be replaced with a state.xml file in future releases). The STATE table contains information that:
§ Tells whether a report should be accepted or rejected if another version of the report already exists in the central database. In other words should the submitted report replace the existing copy or not. This is controlled by matching the existing report status codes to the REPLACEOLD action.
§ Runs processes that will adjust a report's status based on a true-false condition. The GUIDELINE action will set a report's status based on whether the report has passed to guideline check. The RANDOMSELECT action will set a report's status based on a randomly returned true-false condition. When reports enter the system, the REPLACEOLD action is performed on reports with the same previous reference number prior to the new report being added to the tables. The GUIDELINE action is performed on the report after it has been added to the system. The RANDOMSELECT action is performed after the report is added and when a report is approved. Currently reports receive a ST_SUBMIT_ON status when they are first submitted.
The STATE table contains these columns:
§ status - This is always a report status. See the status element in the Status.xml definition above for a list of status.
§ action - This will be REPLACEOLD, GUIDELINE or RANDOMSELECT.
§ positive - Status assigned if a true result is returned. A true result is returned from the GUIDELINE action is the report passed the guidelines. A true result is returned from RANDOMSELECT if a random true is returned (see "randomsampleratio" above).
§ negative - If GUIDELINE (report doesn't pass) or RANDOMSELECT return false, the status specified here is applied.
When are report is first received, the ProcessESSReport class determines the "condition" of the report. The condition of the report will always be one of the following:
§ GOOD_REPORT - Report seems complete, has been written to the central database, and is ready for further process.
§ REPORT_ALREADY_PROCESSED - A report with this previous reference number from this user has already been processed to a point where it cannot be replaced by this report. Therefore, this report cannot be accepted by the central database.
§ BAD_REPORT_CONTENT - The report contains or is missing required content so it cannot be accepted. There are several conditions that describe bad content in more detail so this is a default condition.
§ PERS_NUM_NOT_FOUND - The personnel number of the reporter cannot be verified so this report cannot be accepted.
§ INVALID_CHARGE_TYPE - The report contains invalid payment types (i.e., charges) and cannot be accepted for processing. The primary reason for this is that the payment types in the central database have changed and the ESSProfile generation has not been run.
§ INVALID_EXPENSE_TYPE - The report contains invalid expense types and cannot be accepted for processing. The primary reason for this is that the expense types in the central database have changed and the ESSProfile generation has not been run.
§ PERSISTANCE_FAILED - A failure has occurred while writing the report to the central database. Either the linkage to the central database has failed, in which case the report should be resubmitted, or there is a "programming" error that should be reported to support.
§ FAILED_GUIDELINE - Report has failed the guideline check. The report is still accepted by the central database and will be assigned a status specified in the state table.
Reports that are accepted into the central database are assigned the ST_SUBMIT_ON and processed from that point according to the rules in the three tables/xml files.
The Rules.xml file consists of sub-root "routing" elements. Each routing element is a set of conditions titled "notification." Notifications can have duplicated conditions. Once the condition of the incoming report is determined, all notification elements indicating that condition are used to trigger a notification event(s). The layout of the notification element is:
§ condition - The condition that will trigger this notification
§ routingObject - The object used to route the message. See the discusion on the Status.xml file for a list of these objects/
§ message - The message that is appended onto the ESSProcessReport generated message.
The only routing element currently processed by the system is the "expensereport" element (i.e., name element is "expensereport" in this case).