Configuring an advanced custom prompt

This topic outlines some of the more advanced features of custom prompts and contains an example of how to configure multiple prompts during Clock IN and CLOCK OUT using the options type configuration. Multiple prompts are chained together and additional prompts are displayed that are conditional upon the employee's response to the previous prompt. This is only an example, and you can modify the attributes in this and other examples in this guide to suit your business requirements. The available attributes are listed in Available attributes for custom prompts.

The clock.xml file in your deployment contains the example below of a more advanced custom prompt.

These are the example prompts on how you can configure multiple prompts during a Clock IN using the options type configuration:


** FIRST PROMPT **
	
	<prompt id="SICK_PROMPT" code="SICK" type="options"  >
		<trigger>
			<condition field="swipe.type" operator="=" value="IN"/>
		</trigger>
		<option id="YES" order="6" acceptSwipe="true" data="Y" imageName="accept.png"/>
		<option id="NO" order="5" acceptSwipe="true" data="N" imageName="reject.png" />
		<cancel allowed="true" acceptSwipe="false" data="I" message="SICK_PROMPT_RESPONSE_REQUIRED" swipeRejectedReason="SICK_PROMPT_CANCELLED"  />
		<timeout seconds="15" acceptSwipe="false" data="T" swipeRejectedReason="SICK_PROMPT_TIMEDOUT"  />
	</prompt>
	
** SECOND PROMPT ** 

	<prompt id="MASK_PROMPT" code="MASK" type="options"  >
		<trigger>
			<and>
				<condition field="swipe.type" operator="=" value="IN"/>
				<condition field="swipe.extraData.SICK" operator="=" value="Y"/>
			</and>
		</trigger>
		<option id="YES" order="5" acceptSwipe="true" data="Y" imageName="accept.png"/>
		<option id="NO" order="6" acceptSwipe="true" data="N" message="GET_MASK" messageDisplaySeconds="15" imageName="reject.png" />
		<timeout seconds="10" acceptSwipe="true" data="T" />
	</prompt>

** THIRD PROMPT ** 

	<prompt id="WASH_PROMPT" code="WASH" type="options"  >
		<trigger>
			<and>
				<condition field="swipe.type" operator="=" value="IN"/>
				<condition field="swipe.extraData.SICK" operator="=" value="N"/>
			</and>
		</trigger>
		<option id="YES" order="5" acceptSwipe="true" data="Y" imageName="accept.png"/>
		<option id="NO" order="6" acceptSwipe="true" data="N" message="WASH_HANDS" messageDisplaySeconds="5" imageName="reject.png" />
		<timeout seconds="10" acceptSwipe="true" data="T" />
	</prompt>

** TRIGGER CUSTOM PROMPT **

<prompt id="TIP_PROMPT" code="TIP" type="number" decimalPlaces="2" enableKeyPad="true" enableCardReader="true">
	<trigger>
        <and>
            <condition field="employee.udf1" operator="=" value="10"/>
            <condition field="swipe.type" operator="=" value="OUT"/>
            <or>
                <condition field="employee.flag3" operator="=" value="N"/>
                <condition field="employee.lastStatus" operator="=" value="01"/>
            </or>
            <condition field="employee.supervisorLevel" operator="=" value="0"/>
            <condition field="employee.udf5" operator="=" value="35"/>
        </and>
	</trigger>
	<cancel allowed="true" acceptSwipe="false" data="I" message="TIP_PROMPT_RESPONSE_REQUIRED" swipeRejectedReason="TIP_PROMPT_CANCELLED"  />
	<timeout seconds="15" acceptSwipe="false" data="T" swipeRejectedReason="TIP_PROMPT_TIMEDOUT"  />
</prompt>

In these examples, the employee is asked a question and depending on the response, they are prompted with a second question

Overview of the first prompt

This list shows the actions performed by the first prompt (prompt id="SICK_PROMPT"):

  • Message

    Displays SICK_PROMPT. For example, Are you sick?. You can localize this message in your deployment’s clock.properties.

  • Trigger

    Triggered for every Clock IN transaction due to the condition in the example code above:

    <trigger>
			<condition field="swipe.type" operator="=" value="IN"/>
		</trigger>
  • Type and options

    Displays options to the users in the form of questions as an options-type prompt"`:

    type="options"
  • Menu position and key mapping

    In menu position 6 on the clock, the prompt displays Yes with an image (accept.png). The Clock IN is accepted if the employee selects Yes:

    <option id="YES" order="6" acceptSwipe="true" data="Y" imageName="accept.png"/>

    If Yes is selected, SICK=Y is recorded in the EXTRADATA of the clock transaction.

    In menu position 5 on the clock, the prompt displays No with an image (reject.png). The Clock IN is accepted if the employee selects No:

    <option id="NO" order="5" acceptSwipe="true" data="N" imageName="reject.png" />

    If No is selected, SICK=N is recorded in the EXTRADATA of the clock transaction.

  • Cancel behavior

    If the employee cancels the transaction, Cancel is configured with allowed="true", acceptSwipe="false", and records SICK=I. This transaction also displays the message Transaction Cancelled. Punch will not be recorded configured in SICK_PROMPT_RESPONSE_REQUIRED and logs SICK_PROMPT_CANCELLED with the message Declined to respond to questionnaire in the clock journal for the transaction. You can localize these messages in your deployment’s clock.properties.

    <cancel allowed="true" acceptSwipe="false" data="I" message="SICK_PROMPT_RESPONSE_REQUIRED" swipeRejectedReason="SICK_PROMPT_CANCELLED"  />
  • Timeout behavior
    If the transaction times out, the prompt is configured to wait for 15 seconds, does not accept the swipe, and records SICK=T in EXTRADATA of the clock transaction. This transaction also displays the message Timed out during questionnaire. configured in SICK_PROMPT_TIMEDOUT in the clock journal. 
    <timeout seconds="15" acceptSwipe="false" data="T" swipeRejectedReason="SICK_PROMPT_TIMEDOUT"  />

Overview of the second prompt

This list shows the actions performed by the first prompt (prompt id="MASK_PROMPT"):

  • Message

    Displays MASK_PROMPT. For example, Are you wearing an N95 mask?. You can localize this message in your deployment’s clock.properties.

  • Trigger

    Triggered for every Clock IN transaction when the first prompt recorded SICK=Y in EXTRADATA.

    <trigger>
			<and>
				<condition field="swipe.type" operator="=" value="IN"/>
				<condition field="swipe.extraData.SICK" operator="=" value="Y"/>
			</and>
		</trigger>
  • Menu position and key mapping

    In menu position 5 on the clock, the prompt displays Yes with an image (accept.png).

    <option id="YES" order="5" acceptSwipe="true" data="Y" imageName="accept.png"/>

    If Yes is selected, MASK=Y is recorded in the EXTRADATA of the clock transaction.

    In menu position 6 on the clock, the prompt displays No with an image (reject.png) and a message GET_MASK displayed for 15 seconds:

    <option id="NO" order="6" acceptSwipe="true" data="N" message="GET_MASK" messageDisplaySeconds="15" imageName="reject.png" />

    If No is selected, MASK=N is recorded in the EXTRADATA of the clock transaction.

  • Timeout behavior

    If the transaction times out, MASK=T is recorded and the swipe is accepted after 10 seconds.

    <timeout seconds="10" acceptSwipe="true" data="T" />

Overview of the third prompt

This list shows the actions performed by the first prompt (prompt id="WASH_PROMPT"):

  • Message

    Displays WASH_PROMPT. For example, Have you washed your hands?. You can localize this message in your deployment’s clock.properties.

  • Trigger

    Triggered for every Clock IN transaction when the first prompt recorded SICK=N in EXTRADATA.

    <trigger>
			<and>
				<condition field="swipe.type" operator="=" value="IN"/>
				<condition field="swipe.extraData.SICK" operator="=" value="N"/>
			</and>
		</trigger>
  • Menu position and key mapping

    In menu position 5 on the clock, the prompt displays Yes with an image (accept.png).

    <option id="YES" order="5" acceptSwipe="true" data="Y" imageName="accept.png"/>

    If Yes is selected, WASH=Y is recorded in the EXTRADATA of the clock transaction.

    In menu position 6 on the clock, the prompt displays No with an image (reject.png) and a message WASH_HANDS displayed for 5 seconds:

    <option id="NO" order="6" acceptSwipe="true" data="N" message="WASH_HANDS" messageDisplaySeconds="5" imageName="reject.png" />

    If No is selected, WASH=N is recorded in the EXTRADATA of the clock transaction.

  • Timeout behavior

    If the transaction times out, WASH=T is recorded and the swipe is accepted after 10 seconds.

    <timeout seconds="10" acceptSwipe="true" data="T" />

Overview of the trigger custom prompt

The trigger-based custom prompt of prompt id="TIP_PROMPT in this example is used for the following:
  • It is triggered based on a combination of employee and swipe conditions instead of a basic punch type or previous prompt response.
  • It uses an <and> grouping within the <trigger> tag to define multiple conditions that must all be set to true.
  • If the prompt is canceled, the transaction is rejected and a value of TIP=I is recorded in the clock transaction’s EXTRADATA.
  • If the prompt times out, the transaction is rejected and a value of TIP=T is recorded in the clock transaction’s EXTRADATA.

Other important information

  • Sequence of prompts

    When chaining multiple prompts, ensure that the prompts are arranged in a logical, linear sequence within the clock.xml file. This allows dependent prompts (such as MASK_PROMPT and WASH_PROMPT) to correctly evaluate values recorded by earlier prompts.

    The order of the prompts is important when linking multiple prompts as in the example above. The logic for the prompts must progress in a linear fashion within the clock.xml file.
  • The XML for the prompt must be valid for the prompt configuration to work.
  • The conf/clock.xsd file is useful for advanced users as it outlines the possible attributes and elements that you can have in the clock.xml file. It is strongly recommended that this file is not modified as it may lead to unexpected issues.
  • For the third prompt in this example, you can use value="" to prompt the user to wash their hands regardless of their answer to the previous prompt: 
    trigger punch="in" code="SICK" value=""
  • For the trigger custom prompt, use this configuration to selectively control which employees are shown a prompt based on their data and context, such as displaying a numeric entry prompt only to employees in a specific role during a Clock OUT.