In an effort to avoid the creation of duplicate addresses in STEP, Find Similar functionality can be added to the Store Single Referenced Target Web UI component via the Find Existing action.
The Find Existing action searches objects to identify similar objects using a matching setup that the customer creates and uses for duplicate handling. If similar objects are found after running the action / algorithm, the user is provided with the results in a user-configured detailed list.
The key to Find Existing functionality is the matching setup that the customer creates and uses for duplicate handling. Every time a user enters data into the search fields and clicks OK, the Find Existing search checks the match code values involved, executes the relevant matching algorithm, and provides a set of results, if any are found. If a user is not getting the results set they expect, then the first place to check is the algorithm selected for the Duplicate Handler parameter in the component properties. Bind types are not required for Find Existing functionality since a simple comparator expression, written to compare attributes of the same object type, is used.
Prerequisites
All the steps provided in this topic assume the Web UI designer is in design mode and on the applicable Properties screen prior to starting the configuration process. It is also assumed that all users (designers and end users) have the proper privilege to work with these features. For more information about privileges and user setup, refer to the Users and Groups section (here) and Adding User Privileges for a Group section (here) of the System Setup documentation.
A relevant Match Code and Matching Algorithm needs to be set up before attempting to use the Find Existing action. For more information about setting up and using matching algorithms, refer to the Configuring Matching Algorithms section of the Matching, Linking, and Merging documentation
Using Find Existing on Store Single Referenced Target
This is a very basic example of how the Find Existing action can be used within a Store Single Referenced Target component on an Initiate Item screen. Configuration instructions are after this section.
The end user begins the object (Contact) initiation process by clicking Initiate Contact on the Status Selector Homepage Widget. On the Initiate Screen, the user may enter data into the referenced object attribute value fields. If the user will be doing a Find Similar search after checking for duplicate references, then the user should also enter data for the direct object attribute values.
Before doing an overall Find Similar search on both the direct object and its referenced object, the user clicks the Find Existing button within the Store Single Referenced Target framework to first search for similar objects within that object type. In the example below, the Find Existing action is comparing address objects against address objects to view if a similar address exists in STEP.
The algorithm runs in the background and the configured Dialog List Screen displays. Remember that this is not a standard search and results are based on the matching algorithm running in the background.
Important: As stated at the beginning of this topic, the key to Find Existing functionality is the matching setup that the customer creates and uses for duplicate handling. This is important because the attributes being searched must be part of the list of attributes that Match Codes are generated for. If not, the search will not work as expected.
A maximum of fifty (50) objects are shown at one time on the results list. The user can select one of the objects shown in the results list. Once a selection is made, the OK button is engaged. Clicking OK indicates that you want to use the selected referenced object and use it with creating the direct object.
The attribute value fields within the Store Single Referenced Target component become read only. If the user wants to create a new reference object with the attribute values entered instead of using one from the results list, the user clicks Cancel to exit the results list.
The user can run a Find Similar search, to view if there is a similar contact object that has an address reference that exactly matches the attribute values within the Store Single Referenced Target. Refer to the Find Similar topic
Configuring Find Existing on Store Single Referenced Target
Following the configuration steps below allows end users to search on referenced objects to identify matches within a single object type. If a similar address is found and used, then the direct object will be initiated and linked to selected existing referenced object rather than creating a new referenced object.
- Create a new Initiate Item screen (or use an existing one) and complete configuration, making sure to add and configure the Store Single Referenced Target component. Complete details on configuration can be found in the Initiate Item Screen topic
- While in Web UI designer, navigate to where the Store Single Referenced Target component is located (within a Node Editor on an Initiate Item screen). Double click on Store Single Referenced Target in Child Components > Rows to configure the component.
- Click the ellipsis button (
) to make selections for each of the required parameters. Determine the:
- Object Type of the objects being searched and that will be initiated in to STEP as a reference to the direct object being created.
- Parent to be used for the object type when object is created on save.
- Reference Type to be used when object is created on save.
- Select Duplicate Handler in the dropdown for the Duplicate Handler parameter.
- The Duplicate Handler Properties screen will display. The only required setting is the Matching Algorithm parameter. Click the ellipsis button () to the right of the value field and select a matching algorithm. Click Save.
- For Child Components > Rows, click the Add button.
- Next, select the applicable component (Attribute Value or Attribute Value Group) and choose attributes to be used on the Initiate Item screen (within the Store Single Referenced Target framework) and that are also used within the algorithm. Click Add within the 'Add Component' dialog and you will be returned to the Store Single Referenced Target Properties.
- Under Child Components > Action Buttons, click Add.
- Select Find Existing Actionand click Add.
- Repeat this step and add the Reset Action.
- Double click the Find Existing Action title and open the Find Existing Action Properties.
- Edit the Button Label, if desired. Under Child Components > List Dialog, select List Dialog from the dropdown menu.
- On List Dialog Properties, click Add to the right of the Dialog List Screen value field.
- Create a new screen by selecting Dialog List Screen from the list of available screen types / components. Enter an easily identifiable Screen ID, click Add. The screen ID will automatically populate in the Dialog List Screen value field.
- If a Dialog List Screen already exists, skip the previous two steps and on the List Dialog Properties, select the Dialog List Screen using the dropdown.
- Also on the List Dialog Properties screen, in the Child Components > Buttons field, click Add and select Use Selected Item Action. Click Add, and then click Save in the designer window.
- Before exiting design mode, select the Dialog List Screen ID of the screen you just created from the dropdown menu. In the example above, the screen ID is Dialog List Screen for Contacts.
- Configure the Child Components > Headers section of the Dialog List Screen Properties. Click Add under the value field to set up the attributes that will display in the search results list.
- Add different Dialog List Screen Help Text, if desired. It will display at the top of the template results list.
- Click Save and Close the designer.