Employee Forms Dual "Status" Systems

1. The built-in Status system
2. A Custom Status system that does not replace the built-in system but functions along side it once it is set up.

"Custom Status" and the built-in Status are completely separate and do not overlap.

Each Employee Form is always in one of the built-in status states (e.g. 'Waiting for Approval').   In addition, it can be assigned one a completely separate Custom Status code, once a Custom Status system has been setup.

Why Use Custom Status?

Custom Status codes are typically used either for reporting (for example to help with a custom ReportWriter report), or for Employee Form linking, when a second Employee Form is going to be triggered by responses for an initial form.  Employee Form linkages are described here.  It is not necessary for most Employee Forms.

Components of Custom Status

1. A Codes table containing a code for each of the separate "Custom Status States" you want o create.
2. Using the Codes table discussed in #1 above to add the Custom Status States to an Employee Form.
3. Creating a "Rule" for each separate Custom Status state to "select" that state.

Sample: Custom Status for COVID Vaccination Employee Forms

Building / Configuring Custom Status

Step 1: Create the Codes Table Containing the Custom Status Codes

1. Go to the Setup→Codes screen.
   
2. Create a new Codes table.  
   1. Click the Add Code Table button.   This brings up the "Add Code Table" dialog:
      
   2. Enter a "Code" for the new table (this identifies it internally to SchoolFi).  E.g. VACCINECODES
   3. Enter a Name for the new table.  This is how you will identify it later.  E.g. Vaccine Codes
   4. Select "Employee Form Custom Status" as the Usage.
   5. Click Add to create the table.
      
   6. Clicking Add brings up the Setup→Codes→Modify Table screen for your new table:
      
3. Add your Custom Status Codes to the table. 
   1. Click on Add Code.  This brings up the "Add Code" dialog:
      
   2. Enter the Custom Status Code "Code".  E.g.  EV19     (A Custom Status code is really anything you want to make up).   Each code in the table must be unique:  no repeats.

Enter a Description for your code.   E.g. "I am fully vaccinated"

1. Click Add to add the code to the table:
   
2. Once the code has been added to the table, you can adjust the background and font colors for it.  This allows you to color code your Custom Status codes.
   
3. Repeat steps a to e for each Custom Status code you wish to add to the table:
   

STEP 2:  Use the new Codes Table to Add the Custom Status Code Settings to the Employee Form

1. Return to the Employee Status Form and go to its "Custom Status" screen: 
   1. Go to the Setup→Employee Forms screen
   2. Locate your Employee Form and open it for editing.
   3. Click on the Custom Status second level tab.
      
2. In "Step: Use this Generic Code Set" select the Codes Table you created:
   
3. Click Save to bring the codes into the Employee Form.  This attaches the Codes Table to the Form and enables you to begin creating the Rules that specify when to use which Custom Status code;
   

Step 3:  Create the Rules that Select Which Custom Status Code

1. Click the Add Rule button.  This brings up the Add Rule dialog:
   
2. Select one of the Codes from the Codes Table (which appear in the drop down).
3. Click Add.  This adds the Code to the Custom Status Rules list
   
4. You now enter the Expression Language expression that will "pick" the code you have added.   This Expression MUST evaluate to a Boolean (i.e. true or false) value.   The Expression depends entirely on what you are trying to do:  there are no general rules to make this easy.     Here is a COVID 19 Example with full explanation:
   1. Web Form Question   The Employee Form in this example has a Web Form with the following question in it:
      
   2. Two things are important about this question: 
      1. The Question Code - This is how the question can be referenced in the Employee Form's Custom Status page and elsewhere
      2. The drop down list items:  in this example, these are the items that are going to be used in the Rule Expressions.
   3. The staff member fills in the Employee Form's Web Form - and answers this question.   The Expressions on the Custom Status page will then select the "Custom Status" for the Form.  Here is a description of this how the sample Question shown above can be accessed and used to select a Custom Status: 
      1. ${staffEmployeeForm.questionCodeToAnswerMap['CV19V_1'].answerNoHTML == 'I am fully vaccinated'}   - In this Expression, the staffEmployeeForm.questionCodeToAnswerMap['CV19V_1']. part of the Expression selects the Web Form question to retrieve an answer from.    "staffEmployeeForm.questionCodeToAnswerMap" gets the list of questions and 'CV19V_1'  selects the actual question.  The 'CV19V_1' is the Code for the Question - see the example Question above.
      2. the '.answerNoHTML' selects a certain part  of the answer to the Question.  It ASSUMES that the Question was answered with some text (regardless of the Answer Type of the Question), it strips away any HTML controls found in the text and gives back the text with No HTML.   There are other possible fields to get answer from in the staffEmployeeForm.questionCodeToAnswerMap - typically you will use "answerNoHTML" for all text answers and "dateAnswer" if answer is a date.
      3. If the answer is text, you can compare it directly to what you are looking for:  staffEmployeeForm.questionCodeToAnswerMap['CV19V_1'].answerNoHTML == 'I am fully vaccinated'.    Here, '==' is the operator which means "is equal to" so this is asking if the staff member selected the "I am fully vaccinated" answer to the question.
      4. If the full Rule is:   ${staffEmployeeForm.questionCodeToAnswerMap['CV19V_1'].answerNoHTML == 'I am fully vaccinated'}  and the staff member DID select "I am fully vaccinated" this Expression will be TRUE.  Because it is TRUE the Custom Status code is selected.
5. You must add a Rule for each Custom Status code you want to be selectable as a Custom Status for the Employee form: 
   1. Click on the brown box to bring up the first screen of the Macro Browse:
      
   2. Locate the "staffEmployeeForm" entry and click on the Choose a field button corresponding to it.  This brings up the second level of the Macro Browser for the staffEmployeeForm table:
      
   3. Scroll down until you find the questionToAnswerMap entry and click on the Choose a Field button corresponding to it.  This will bring up a third Macro Browser panel, for the questionToAnswerMap bean:
      
   4. Now scroll down until you locate the 'answerNoHTML' field (or the 'dateAnswer' field if you are using a date) and click on the Choose button corresponding to it.   This will create your macro:
      
   5. Now you must customize it for your particular question.    
      1. ${staffEmployeeForm.questionCodeToAnswerMap['CODE'].answerNoHTML}  - Replace the 'CODE' with the code for your Question:
      2. ${staffEmployeeForm.questionCodeToAnswerMap['CV19V_1'].answerNoHTML}
      3. Now you can add the test:   ${staffEmployeeForm.questionCodeToAnswerMap['CV19V_1'].answerNoHTML == 'I am fully vaccinated'}
      4. Remember that the Rule must evaluate to TRUE or to FALSE.