Manual Input Form+

Overview

When to use it

Use this symbol when you need to:

• Give operators a guided form for a recurring set of entries, such as a shift log or a lab sample.
• Group related fields into labeled sections and arrange them in columns.
• Use the control that fits each value: switch, buttons, drop-down list, slider, number box, text box, or date and time.
• Warn operators, or stop them, when a number is outside its limits.
• Mark fields as required and record which operator saved the form.

Choose Manual Data Entry+ when each data source needs its own timestamp, or when you need to import or paste values, enter a block of time slots, or decide what happens to a value that already exists. Choose Quick Input+ to write one value immediately, without a Save step.

Before you begin

• Use writable PI Points or AF attributes, and make sure the operators have write permission for them.
• Turn compression off on every PI Point you use for manual entry. With compression on, the PI System can discard a manually entered value that falls inside the compression deviation.
• Set Step to On for numeric PI Points. With Step off, the PI System interpolates between stored values, and trend and table symbols show misleading values between your entries.
• Decide which fields operators fill in on every save. Save also writes prefilled values, as described under Use the symbol.

Add and set up the symbol

1. Select Manual Input Form+ in the PI Vision symbol gallery, and drag the PI Points or attributes onto the display. Each data source becomes one field.
2. Right-click the symbol and select Configure Input Form....
3. Under General, enter a Title and set Columns.
4. Under Attributes, select each data source and enter its Label.
5. Under Time, keep Default at Current.
6. Close the configuration pane, enter a value in at least one field, and select Save. If Require Confirmation is on, select Confirm.

A Save Successful message appears, Last Input shows the time of the save, and the fields return to their prefilled values.

Important: Save writes to the PI Data Archive. Saved values cannot be undone from the symbol.

Common tasks

Arrange the fields in sections and columns

Use this to turn a long list of fields into a form that operators can scan.

1. Right-click the symbol and select Configure Input Form....
2. Under General, set Columns (1) to the number of columns, and enter a Title (2).
3. Set Label Placement (3) to Title to show the label above each field, Placeholder to show it inside an empty field, or None to hide it.
4. Set Group (4) to Custom. Category and Description group by the AF category or the description of each data source instead.

1. Under Attributes, select a data source in the list.
2. Enter the field name in Label (1) and the section name in Group (2). Data sources with the same Group share one section header.
3. Set Column Span (3) to let a wide control, such as a row of buttons, cross several columns. For a string data source, set Row Span to make the text box taller.

The fields appear in the order of the list, and the arrow buttons under the list move the selected data source. Sections appear in the order of their first field. When the symbol is too narrow for the columns, the form uses fewer columns. Min Width sets the narrowest a column may become.

Choose a control for each field

Use this when the default control does not fit how operators think about the value. The data type decides which controls are offered.

1. Under Attributes, select the data source.
2. Select the control in Control Type (1).
3. For a boolean data source with Switch or Buttons, enter the Off Text (2) and On Text (3), for example Stopped and Running.
4. For a digital data source, type a replacement name for any state in the list under Control Type. The state itself does not change.

The form shows a switch (1), a number box (2), a drop-down list (3), a slider (4), a text box (5) and a date and time box (6):

A slider takes its scale from Limit Mode: Database uses the range the data source reports, and Custom uses Max and Min. Step Size sets the increments. Use a Number box for an optional value, because a slider always holds a value.

Check entries against limits

Use this to catch typing mistakes in numeric values. The check runs when the operator leaves the field, and again at Save.

1. Under Attributes, select a numeric data source.
2. Set Enable Input Limits (1) to Yes.
3. To block out-of-range values instead of only warning, set Hard Limit (2) to Yes.
4. Set Limit Mode (3) to Database to use the limits the data source reports, or to Custom.
5. For Custom, enter Max and Min (4).
6. Optionally, enter a Message (5) with guidance for the operator.

Without Hard Limit, a value outside the limits opens a Limit Warning. Cancel puts the previous value back. Continue keeps the value, and the field keeps an orange outline.

With Hard Limit, the dialog is titled Invalid Value and offers only Cancel, which puts the previous value back.

At Save, a hard-limit value stops the save and a message lists it. A value that the operator has not already accepted with Continue is listed once in a Limit Warning with Cancel and Confirm.

Require fields and prefill the user name

Use this to make sure a field is filled in, and to record which operator saved the form in a string PI Point or attribute.

1. Under Attributes, select the string data source.
2. Set Required (1) to Yes. Required fields show an orange asterisk next to the label.
3. Set Allow Edit (2) to No so that operators cannot change the name.
4. Set Prefilled Value (3) to User.

The field shows the PI Vision user name, and every save writes it with the other values. When a required field is empty, Save shows a Missing Inputs warning and outlines the field. The warning names the data source by its original name, not by the label you gave it.

Prefilled Value also offers Last Value and Custom. See Attributes.

Save the form with one timestamp

Use this to record all values of a form at the same moment, or at a time you choose. Every value of one save gets the same timestamp.

1. Under General, set Require Confirmation (1) to Yes to make operators confirm each save.
2. Optionally, set Set Questionable flag (2) to mark every written value as questionable, and Show Last Input Timestamp (3) to show Last Input in the toolbar.
3. Under Time, set Default (4) to Current (the time of the save), Custom (a time you enter), Display Start Time or Display End Time.
4. Set Allow Edit (5) to On to let operators change the time in the toolbar.

To save at another time, an operator enters an absolute date and time or a PI time expression such as *-1h in the time field next to Save. The field converts an expression to an absolute time. With Require Confirmation on, Save opens a Save Confirmation that states how many data points will be written.

Use the symbol

• Enter, then save. Typing only stages a value. Last Input next to Reload shows the latest time among the values of the form.
• Save writes every field that holds a value, including prefilled values the operator did not change. Typing one value in a form whose other fields are prefilled can write several data points, and the Save Confirmation counts them.
• After a save, the form returns to its prefilled values. A field prefilled with Last Value follows the archived value until the operator edits a field.
• An orange outline marks a value outside its limits or a required field that is empty.
• Read-only fields show their value as plain text. They are written when they hold a value.
• The controls do not respond while the display is in edit mode.

Configure the symbol

Right-click the symbol and select Configure Input Form.... The pane has the groups Attributes, General, Time, Style and Numbers, followed by the standard Web API, License Status, Help and About groups.

Attributes

Select a data source in the list, then set it. The list order is the field order.

General

Time

Style and numbers

Multi-state colors come from Configure Multi-State... on the right-click menu. They color a field by its value, as a fill or as text.

Troubleshooting and limitations

Limitation: All values of a save share one timestamp. For a different time per data source, use Manual Data Entry+.

Limitation: A value saved at a timestamp that already holds a value replaces it. There is no rule to protect existing values, and no CSV import or paste.

Limitation: Editing a saved value is a historical change. Follow your site's correction and audit procedure.