Now it’s time to choose the fields from each web service to include with the prompt.
The first thing you will notice when visiting this tab after selecting the web services is that an organization field has likely already been created for each of the web services on the prompt. These are the controlling organizations and were automatically created for you as mentioned in the Web Services tab discussion.
The minimum required data for creating a field record is Process Group-Web Service, Field, Field Label, Field Type, Display Type, Sequence, and Next Sequence. Additional fields may be required depending on the Field Type value selected. Prior to selecting fields, you must identify the web service you want to deal with using the Process Group-Web Service field.
There are two options for adding fields:
-
Click the Select Multiple Fields link to for the ability to select more than one field at a time.
-
Click the Field lookup to choose a single field. When a Field value is selected, the system defaults all required data, but allows the data to be changed.
An explanation is provided below for most of the fields (see the image in ):
Process Group-Web Service
This dropdown displays each record from the Web Services tab. You must select a Process Group-Web Service prior to clicking a link button or filling in any of the detail fields. The available fields and lookup values on this page are driven by the web service itself and whether it is an insert, update, or delete web service. This value is updateable only in insert mode.
Field
Displays the selected field as it exists at the web service level. See the Field Label for boiler text shown on the front end for the selected Field.
Field is protected in update mode.
Field Label
The system delivered boiler text is retrieved here whenever a Field is selected. In most cases, you will see the same text here as you would see on a screen elsewhere in the application that uses the selected web service and field.
The default Field Label may be updated to display the desired text when web service prompt screen is displayed to the user.
Field Type
Field Type is defaulted based on the system delivered type for the selected field (that is, alphabetic, numeric, date, free format text, or check box). This value may be updated. If ‘numeric’ is selected the system expects a number to be entered in the field. A ‘date’ type will cause a calendar lookup button to be displayed next to the field on the prompt screen while choosing ‘check box’ will have the field appear as a check box.
In addition to these more traditional field types several other values are available in this dropdown for selection: fixed, computed, retrieved field, and key field.
Choosing ‘fixed’ will enable the Fixed Data field allowing the user to enter the value which will always be used by this field on the prompt. The Display Type for a ‘fixed’ field can only be ‘hidden’ or ‘protected’. See Fixed Data below.
Choosing ‘computed’ will enable the Computed Data field allowing the user to enter a database Select statement. The Display Type for a ‘computed’ field can only be ‘hidden’ or ‘protected’. See Computed Data below.
Choosing ‘retrieved field’ will enable the Retrieve from Group-Web Service and Retrieve Field fields. See Retrieve From Group-Web Service and Retrieve Field below. Also, Field Type will default to ‘hidden’.
‘Key field’ will only be displayed in the Field Type lookup when a sync (update) or delete web service is selected for Process Group-Web Service. Choosing ‘key field’ will enable the Query Web Service field. See Query Web Service below. When defining fields for an update or delete web service you must, at a minimum, select fields corresponding to the key and required fields in the web service. The key fields are fields necessary to uniquely identify a record in the database.
Display Type
Field Type is defaulted based on the system delivered type for the selected field (that is, hidden, protected, optional, or required). This value may be updated. Keep in mind that the prompt screen design feature will not allow you to change the field type to be less restrictive than the value entered here. For example, if you set the Display Type for a field to ‘required’ on the Fields tab the screen design feature on the prompt screen will not allow you to change the Display Type to ‘optional’. This behavior is like normal screens within HxGN EAM™ in that screen designer cannot be used to loosen the delivered field display type.
Sequence
The Sequence value identifies the tab order for the fields within the selected prompt when executing the prompt screen. When tabbing the cursor, focus will move to the field identified by the Next Sequence, unless a branching condition (Go To) has been defined. See If Data Is, Pattern, Go To below. Valid values are integers in the range of 1 to 99999999.
The default Sequence for each field is assigned in the following way, if INCRLINO = 10 and WSPFSEQ = 100:
1st field selected for the Process Group-Web Service: [(Process Group) X (WSPFSEQ)] + INCRLINO. Therefore, the 1st field Sequence for Process Group 10 would be [(10) X (100)] + 10] = 1010.
The 2nd field selected for Process Group 10: (Greatest Sequence for the Process Group-Web Service) + (INCRLINO). Therefore, the 2nd field Sequence for Process Group 10 would be (1010) + (10) = 1020.
The system will insure that each field for a given Process Group – Web Service is grouped and processed together on the prompt screen that is, the system must know which fields are to be processed with which web services. This is important when prompt screens contain multiple web services. The system will verify that both following are true.
The selected Sequence is greater than the largest Sequence already entered for all previous Process Groups – Web Services
The selected Sequence is less than the smallest Sequence already entered for all subsequent Process Groups – Web Services.
Next Sequence
The Next Sequence value identifies where the cursor will be focused once leaving the field identified by the Sequence value. In general, the Next Sequence value for the previous field should be equal to the Sequence value for the next field. Refer to the grid records in the image on page 21.
The cursor will always move into the field identified by the Next Sequence unless a branching condition (Go To) is met. Valid values are integers in the range of 1 to 99999999.
Minimum Length
The Minimum Length defaults to ‘0’. However, this can be changed to allow something greater if necessary.
Minimum Length is required for ‘alphabetic’ and ‘free format text’ types. It will be optional for ‘numeric’ and protected for other field types.
Minimum Length must be a positive integer or zero.
Maximum Length
The Maximum Length will default to the maximum size identified in the web service for the selected field if the Field Type is ‘alphabetic’ or ‘free format text’. It is required for these types. If the field is ‘numeric’ the value will be blank and optional. If no Maximum Length is entered for ‘numeric’ types the system will limit entry on the prompt screen to 24 characters. Maximum Length for other field types will be protected.
Maximum Length must be a positive integer (that is, invalid Maximum Lengths include zero, negative numbers, decimals, and values greater than maximum field length defined in the web service).
Fixed Data
Fixed field values are always populated as soon as the prompt screen is loaded. ‘Fixed’ fields work similarly to default values elsewhere in the HxGN EAM™ system. ‘Fixed’ means that they can only be hidden (the default) or protected. Therefore, the user cannot change the data in these fields when prompt screens are used.
Computed Data
Choosing ‘computed’ will enable the Computed Data field allowing the user to enter a database Select statement. The result of the Select statement will be populated into the ‘computed’ field. Computed field values are always calculated when the prompt is saved. In other words, when the user views the prompt screen ‘computed’ fields will not display any value and the field can only be hidden (the default) or protected. The system populates these fields at save time.
These Select statements can contain various operators as well as Oracle and SQL functions. Theoretically, if the statement can run successfully on the database, it can be used.
For example, if the prompt field should always be populated with today’s date the administrator can make the field ‘computed’ and enter a Select statement such as "Select sysdate from dual;" into the ‘computed data’ field.
The system also allows the referencing of other prompt fields as a variable inside the Select statement. If we have a prompt that contains an Employee field (Sequence = 1010) and a field representing the employee’s Department (Sequence = 1020), we can write a Select statement in the Computed Data field which takes the value entered in the Employee field and retrieves that employee’s department into the Department field. The syntax for referencing a value in another prompt field would be ":<prompt sequence #>. For example, the Computed Data statement would look something like this:
SELECT per_mrc FROM r5personnel WHERE per_code =:1010;
Prompt fields can also be referenced in this way in the Query Code (both LOV definition and Retrieve Values) and Mobile Query Code prompt fields. See Query Code and Mobile Query Code below.
Pattern Match
Pattern Match is only enabled when the Field Type is ‘alphabetic’ or ‘free format text’. It is used to establish an acceptable pattern for the data entered into the field on the prompt screen.
When the field is enabled it is also made required. A default value of ‘%’ (wildcard) is loaded, meaning that any alphanumeric entry into the selected field on the prompt screen will be accepted.
Below are other wildcards that are supported by the Pattern Match feature:
. (period) – Represents a single alphabetical character, A through Z
# (pound sign) – Represents any single number, 0 through 9
_ (underscore) – Represents any single alphanumeric character, A through Z and 0 through 9
% (percent) – Represents a string of alphanumeric characters
, (comma) – Represents an OR condition
; (colon) – Represents a THROUGH condition
Any character(s) or number(s) – Indicates that exact character or number in that position
! Any character(s) or numbers(s) – Indicates data entered should not match what follows the "!"
Parent Screen Key Field
This lookup will display the key fields for the screen selected as the Parent Screen on the prompt record view. It only applies when the prompt Type = ‘stand-alone screen’. The purpose of this field is to link the key field(s) on the Parent Screen to the key field(s) on the web service prompt screen. When a user is highlighted on a record from the Parent Screen then clicks the web service prompt tab the system can pass the key field value to the tab thus eliminating the need to enter the value(s) manually.
Query Code
Web service prompt fields do not, by default, inherit lookups from the base field they represent. For example, when using the Add Work Order web service, the Equipment field will not contain a lookup button with validated values when the prompt screen is executed. It will be displayed as a text field, and the user will need to enter valid equipment or they will receive an error message when submitting the record.
The Query Code provides the administrator a way to associate a look up to the corresponding field. The Query Code field will show all queries (entered on the Queries screen) that are NOT Inbox or KPI queries (that is, all Data Collection, Normal, and Lookup queries will be displayed).
So, if you want the work order equipment field to display valid equipment on the prompt screen you must first create a query that describes what the equipment lookup should contain. The following Query could be used to describe the work order equipment lookup:
SELECT obj_code, obj_desc FROM r5objects WHERE obj_obrtype IN ('A', 'S', 'P', 'L');
Additional conditions could be added to this Select statement that would limit equipment even further to those whose organization matches the user’s organization. For example:
-
SELECT obj_code, obj_desc FROM r5objects WHERE obj_obrtype IN ('A', 'S', 'P', 'L')
-
AND obj_org IN (SELECT uog_org FROM r5userorganization WHERE uog_user = 'puser’);
-
Query Code is not available for ‘check box’, ‘computed’, ‘fixed’, or ‘retrieved value’ field types.
Query Code cannot be selected for a custom field. If a custom field that contains a lookup is selected as a field on a web service prompt the system will display a lookup and the associated list of values when the prompt screen is executed by the user.
Mobile Query Code
Mobile Query Code works in much the same way as the Query Code field; however, it only works when executing the prompt screen on a mobile device running HxGN EAM™ Mobile. When running HxGN EAM™ Mobile and a connection is not available with the HxGN EAM™ Extended application server, the device will run the query defined in the Mobile Query Code on the local mobile tables to display a list of values for the prompt field.
It should be noted that if a server connection is available when the prompt screen is executed the system will not use Mobile Query Code to display the list of values but will instead use only the Query Code field.
Retrieve From Group-Web Service and Retrieve Field
Choosing ‘retrieved field’ will enable the Retrieve from Group-Web Service and Retrieve Field fields. This Field Type would be selected if you wanted to return a field value from the database that was posted as part of a previous web service in the current web service prompt and populate it into a field that is part of a subsequent web service in the prompt.
For example, say you want to create a new piece of equipment then create an installation work order for that equipment. This could be accomplished using a single web service prompt and the ‘retrieved field’ functionality. First create the prompt containing the Add Asset Equipment web service followed by the Add Work Order web service. When the user enters data into these 2 web services they will not know the equipment code to enter on the work order because it has not been created yet (if asset codes are created by the system and not entered manually). The solution is to create the Equipment field on the work order web service as a ‘retrieved field’ (meaning the value will be retrieved from the Add Asset Equipment web service). In this case, the Retrieve from Group-Web Service will be ‘Add Asset Equipment’ and the Retrieve Field would be ‘Asset’ (asset code). When the prompt is executed by the user the system will create the new asset using the Add Asset Equipment web service then return the generated asset code to the Add Work Order (asset code field) so the new work order can be successfully created.
Only fields which are key fields in the Retrieve From Group – Web Service can be successfully retrieved for use in a subsequent Process Group – Web Service. For example, when creating a work order (Process Group 10) and then a work order activity (Process Group 20), only work order number and work order organization can be successfully retrieved from Process Group 10 to be used in Process Group 20. Other fields which are not work order key fields (that is, work order type, department, etc.) should not be selected for Retrieved Field.
Query Web Service
If a ‘sync’ (update) web service and Field Type = ‘key field’ is selected the system will enable the Query Web Service field. The system will populate Query Web Service with the "GET" web service corresponding to the Process Group – Web Service specified.
When a prompt screen containing an update web service is executed there are 3 basic steps involved:
-
System will display the key field(s) for the web service so the user can enter the data necessary for the system to uniquely identify the desired record.
-
System will query the record identified by the key field(s) information entered by the user and display the defined data on the web service prompt screen.
-
User makes the necessary updates to the record and commits the changes.
The query necessary in step 2 is a ‘GET’ web service that retrieves the uniquely identified record for display to the user. Therefore, the ‘GET’ web service must be known in the prompt for it to be executed properly. In most cases, there is only one ‘GET’ web service associated with the update web service in question. Therefore, the system populates it automatically and the user doesn’t have to do anything else with this field.
See Selecting Fields for Update (Sync) and Delete Web Services below.
Unmapped Field
Sometimes it is necessary to collect ‘extra’ data that is never intended to be saved to the database. Perhaps you need a placeholder for a piece of data which will be used to calculate the value of some other field in the prompt.
The ‘unmapped field’ check box is used to designate a field for this purpose. Select a Process Group-Web Service value then check the ‘unmapped field’ check box (checkable in insert mode only). The system will clear and protect the Field field. This is because there is no web service field related to an ‘unmapped field’ field. Remember, any value typed into an ‘unmapped field’ field will not get processed into the database, except via an indirect route (that is, used in a calculated field or as a variable in a Query Code).
‘Key field’ and ‘retrieved field’ Field Type values are not valid when ‘unmapped field’ is checked.
Use Previous Value
When this check box is checked for a web service prompt field and the prompt screen enters insert mode, the system will remember the previous value submitted for the field and default the value into the field for the next record. It’s a default value, of sorts; except that the value may not be fixed. Instead it is always the same as the value entered on the previous record.
If Data Is, Pattern, Go To
These three fields go together and define a branching condition in the tab sequence between fields on a web service prompt. The branching condition dictates the tab sequence can change depending on the data entered in the field for which the branching condition is defined. Pattern and Go To are not enabled until If Data Is is specified.
For example, let’s say you are collecting asset data in the field. Part of the collection process is to record data on the condition (the use of this term here has nothing to do with branching conditions) of the asset. If the asset condition is ‘poor’ there are 4 additional pieces of data to be collected which are not important if the asset condition is ‘good’. The prompt used for this purpose must contain these 4 extra fields, but in some cases, they are not necessary. Therefore, the Sequences assigned to these fields are the greatest Sequences (1140, 1150, 1160, and 1170). A branching condition could be established on the asset condition field (1130).
The branching condition says that if the asset condition = POOR then the cursor will tab into the 4 extra fields before returning to the first field to begin inserting the next record. Else, these 4 extra fields will be skipped. The branching condition in this example can be setup as follows on the asset condition field (Sequence 1130):
-
If Data Is = ‘=’
-
Pattern = ‘POOR’
-
Go To = ‘10’, where Sequence 10 is the first field in the prompt
The Go To value must be an integer in the range of 1 to 99999999.
Clear Previous Values Starting From Go To Target Field
This check box is only available for fields on which branching conditions are specified. It impacts fields whose ‘use previous value’ flag is checked and a return prompt is triggered via branching condition logic.
If the check box is checked the system will use previous values for fields whose sequence is prior to the ‘go to’ target field. If the check box is unchecked the system will use previous values for fields whose sequence is prior to the ‘go to’ source field.
Just a couple of key points here… the check box does NOT impact fields whose ‘use previous value’ flag is checked and a normal return is encountered as is the case when tabbing out of the last prompt field. And, the check box does NOT impact the prompt when the ‘go to’ target field sequence is > ‘go to’ source field.
Select Custom Fields (link button)
If the Select Custom Fields link button is clicked, the system display a pop-up containing custom fields available for the Process Group-Web Service (that is, custom fields that are already selected for the Process Group - Web Service will not be available in the pop-up).
Custom field code will be defaulted into the Field field while the custom field description will become the Field Label. If the custom field is related to the * Class of the DEFORG organization, the system will enable the Sequence and Next Sequence fields while providing a default value for each similarly to normal web service fields. When executing the prompt screen the system will display these custom fields intermingled with normal fields based on their Sequence. The Screen Designer feature can be used to move these custom fields around the prompt screen. See Step 4: Use screen designer to make final screen configuration changes on page .
When the custom field is not related to the * Class of the DEFORG organization, the system protects Sequence and Next Sequence and does not assign values for them. The reason being is that these fields will always be displayed in the Custom Fields container, for the related web service, when the prompt screen is executed. These custom fields cannot be moved outside the Custom Fields container using Screen Designer.
No custom fields will be displayed if a Process Group-Web Service has not been selected.
Selecting Fields for Update (Sync) and Delete Web Services
When selecting fields for update and delete web services it is critical to identify those fields in the web service are necessary to uniquely identify record represented by the web service. These will be database key fields and the controlling organization.
Remember, the controlling organization field is always added automatically when the web service is saved on the Web Service tab (controlling org. check box is checked on the Fields tab), so adding this field manually is not necessary. But selecting the key fields is necessary. For example, when the Sync Asset Equipment (update) web service or the Delete Asset Equipment web service is selected for Process Group-Web Service you must add the equipment code as a key field (that is, key field should be chosen as the field type).
One additional piece of data must be supplied to key fields for update web services. That is the Query Web Service. This field will become enabled when a display type of ‘key field’ is chosen for an update web service. The Query Web Service is used by the system to query the record and display relevant data to the user prior to updating. Most of the time the system will fill this field in automatically, but you may need to select it from the lookup.
For update web services, now you are free to select additional fields which should be available for viewing or updating when the prompt is executed. See Using Update (Sync) and Delete Web Services.
When selecting fields for a delete web service it is only necessary to select the key fields and controlling organization since the system does not query and display the record prior to deleting it. See Using Update (Sync) and Delete Web Services. on for executing these prompts).
-
Fields cannot be defined until web services are selected on the Web Services tab.
-
A field cannot be duplicated for the same Process Group-Web Service and prompt.
-
Once a field is selected it will not be available for selection in the field lookup options when clicked.
-
If an insert or update web service is selected and the entity related to the web service has user defined fields (UDFs) available, the lookup will display these UDFs along with the normal fields related to the web service.
-
The system will not provide an error or warning of any kind on the setup screen if the user fails to associate the necessary ‘required’, ‘key’, or ‘retrieved’ fields for the selected Web Service. The prompt will not operate correctly when the user executes the prompt screen.
-
There is no capability to define language translations for Field Labels. When the prompt machine is executed, regardless of the user language the Field Labels will show exactly as they were entered on the Field page for the selected Web Service Prompt. If a customer wants prompts to be displayed in multiple languages, then a separate prompt must be created for each language.
-
While setting up web service prompt fields, if the user enters Next Sequence that does not exist in the prompt there will be no error or warning provided on the setup screen. However, when the user attempts to execute the prompt the system will provide an error at that time.
-
If a field is designated as the ‘controlling org.’ for the selected Process Group-Web Service, the system will not allow this field to be deleted (that is, remember that it is automatically added for you when the web service is selected on the Web Service tab). The only way to remove a ‘controlling org.’ field is to delete the web service itself from the Web Service tab, which in turn will delete all related fields, including the ‘controlling org.’.
-
Fields which are not flagged as ‘controlling orgs’ can be deleted; however, following confirmation, any related fields on the Retrieved Values tab will be automatically deleted.
-
Radio buttons, link buttons, and generic buttons are not supported with web service prompts.
-
As previously stated, if a web service is related to an entity which has user-defined fields (UDFs) these UDFs will be displayed in the Select Multiple Fields link pop-up or the Field lookup. If selected, the UDF will always get a Field Type = Alphabetic, Numeric, Check box, or Date by default based on their pre-defined field type.
-
Custom fields are not available for selection if a delete web service is selected.
-
It is only necessary to select the ‘key fields’ for delete web services. This is because the user need only enter key field information for the system to uniquely identify the record for deletion. It should be noted that once the user enters the key field information and saves (or tabs out of the last key field) the system will go to the backend and delete the record. Contrary to the ‘GET’ step that occurs when dealing with an update web service, no record will be retrieved and displayed prior to deletion for delete web services. Therefore, there is no need to add fields to the prompt which are not key fields.
-
This screen is a system administrator function. Changes made to prompt fields on this page will override any changes made using the prompt screen designer option. See Step 4: Use screen designer to make final screen configuration changes on page . For example, changing field Sequence here will reset the field position on the prompt screen based on this new Sequence, even if the user has used screen designer to locate the field to a position on the screen that is more to his/her liking. Changes to display type and boiler text could result in similar consequences.