Administering relationships

You can start and stop relationships from either System Monitor or from System Manager in the InterChange Server Component Management view.

Viewing relationship states

You can view the state of a relationship either by logging on to System Monitor and opening a view that contains relationship status or by using the InterChange Server Component Management view in System Manager. To log on to System Monitor, follow the instructions in Steps for logging on to System Monitor. To use the InterChange Server Component Management view of System Manager, follow the instructions in Steps for connecting to an InterChange Server Express instance..

The state of a relationship is represented differently, depending on which tool you are using.

Steps for using System Monitor to view relationship states

Perform the following steps in System Monitor to view relationship states:

  1. Open the System Overview view.
  2. Under Views, click the Maps and Relationships link. The Map Status and Relationship Status monitors appear (see Figure 11).

When the product is installed, the default view is set to System Overview, and the default monitor contained in that view is set to System Overview. These defaults can be changed to suit your monitoring needs. See Setting up views to monitor the system for instructions.

Steps for using System Manager to view relationship states

Perform the following steps in System Manager to view relationship states:

  1. Connect to the InterChange Server Express instance that contains the relationship you want to view. See Steps for connecting to an InterChange Server Express instance for instructions on connecting to an InterChange Server Express instance.
  2. In the InterChange Server Component Management view, expand the InterChange Server Express instance, then expand the Relationships folder and expand either the Dynamic or Static folder. The relationships appear under either folder and have different icons to indicate their different states (see Figure 33).

    Figure 33. Relationships folder in the InterChange Server Component Management view


Table 10 lists the relationship states represented by the display color and describes what actions can be performed during that state.

Table 10. Relationship States

Relationship state (color) Description
Active (green) Relationship is ready to run and available for use. To use Relationship Manager on a relationship, the relationship must be in the active state.
Inactive (red) Relationship is not ready to run or available for use. When the relationship is stopped, it becomes inactive -- all current jobs in the queue are completed and no new jobs are accepted. To modify a relationship definition, it must be in this state.
Unknown (gray) Relationship does not have a compatible run-time schema. To create a compatible run-time schema, from Relationship Designer Express, save the relationship with the Create run-time schema option selected. The state changes to Inactive, at which point the relationship can be started.

Starting and stopping relationships

Relationships are used to establish associations between business object attributes that cannot easily be mapped. The tool used for creating relationships is Relationship Designer Express. For more information about Relationship Designer Express, see the Map Development Guide.

When you expand the Relationships folder in the InterChange Server Component Management view, two subfolders appear: Dynamic and Static.

This section describes the following topics:

"Relationship activation"

Steps for starting and stopping relationships

Relationship table caching

Relationship activation

For a relationship to be executable, it must be activated. However, you cannot modify a relationship when it is active. Therefore, you must stop the relationship, modify it, and then restart it. See Appendix B, Requirements for restarting IBM WebSphere InterChange Server Express system components to find out what changes require relationships to be restarted.

Steps for starting and stopping relationships

Perform the following steps to start and stop relationships in System Monitor:

  1. From the System View window (see Figure 11), select Show Maps and Relationships from the View menu. The Maps and Relationships columns appear next to Collaborations and Connectors.
  2. Right-click a relationship, then select either Start RelationshipName or Stop RelationshipName.

Perform the following steps to start and stop relationships in System Manager:

  1. Expand the Dynamic or Static folder in the InterChange Server Component Management view (see Figure 33).
  2. Right-click the name of a relationship, and click Start RelationshipName or Stop RelationshipName.

Relationship table caching

As part of the design process of a static relationship, a developer can indicate whether the relationship's tables are to be cached in memory. A static relationship is one whose data does not change frequently so is a good candidate for table caching. If the developer has indicated that the static relationship's tables can be cached, you can control whether to enable caching from System Manager. System Manager lists all static relationships in the folder labeled Static in the Relationships folder.

Note:
For information on how to design a static relationship so that its tables are cached in memory, see the Map Development Guide.

Steps for enabling Caching

Perform the following steps to enable relationship table caching for a static relationship:

  1. Expand the Relationships folder in System Manager.
  2. Expand the Static folder in the object browser to locate the static relationship whose tables you want to be cached.
  3. Right-click the static relationship to determine its current cached state. If the Cached option appears with no check mark to the left, caching for that relationship is currently disabled. Select Cached to enable caching.

When the Cached option appears with a check mark to the left, InterChange Server reads the relationship tables into memory the next time the run-time data is accessed.

Steps for disabling Caching

Perform the following steps to disable relationship table caching for a static relationship:

  1. Expand the Relationships folder in System Manager.
  2. Expand the Static folder in the object browser to locate the static relationship whose tables you do not want to be cached.
  3. Right-click the static relationship to determine its current cached state. If the Cached option appears with a check mark to the left, caching for that relationship is currently enabled. Select Cached to disable caching.

When the Cached option appears with no check mark to the left, InterChange Server reads run-time data from the tables in the relationship database.

Steps for reloading the Cached tables

Perform the following steps to tell InterChange Server to reread the relationship's tables into memory with the Reload feature:

  1. Expand the Relationships folder in System Manager.
  2. Expand the Static folder in the object browser to locate the static relationship whose tables you want to be reloaded.
  3. Right-click the static relationship to determine its current cached state. If the Cached option appears with a check mark to the left, caching for that relationship is currently enabled. Therefore, the Reload option is enabled.
  4. Select Reload to reload the static relationship's tables.

InterChange Server reloads the cached relationship tables by rereading the tables from the relationship database into memory. This option is useful when the static relationship's tables are updated directly in the database through SQL statements. To get the more current version of the tables into cache, select the Reload option.

Steps for tracing Cached tables

Perform the following steps to tell InterChange Server to log a trace message each time it loads and unloads relationship tables in memory:

  1. Edit the InterchangeSystem.cfg file.
  2. Set the RELATIONSHIP.CACHING configuration parameter to five (5) in the TRACING section:
    RELATIONSHIP.CACHING=5
    

    InterChange Server Express routes these messages to the trace file (if one is configured). By default, InterChange Server Express does not generate trace messages when it loads and unloads the relationship tables. Trace levels less than five (0-4) do not produce messages either.

Using Relationship Manager

Relationship Manager allows you to view and perform operations on relationship run-time data, including participants and their data. For background information about relationships, see the Map Development Guide.

You create relationship definitions with Relationship Designer Express. At run time, instances of the relationships are populated with the data that associates information from different applications. This relationship instance data is created when the maps that use the relationships start. The data is stored in the relationship tables specified in the relationship definition. Relationship Manager provides a graphical interface to interact with the relationship tables regardless of the database vendor.

For each relationship instance, Relationship Manager displays a hierarchical listing of its participant definitions and participant instances, which are a set of key and non-key attributes. The relationship tree also provides detailed information about each of the participants in the relationship instance such as the type of entity, its value, and the date it was last modified. A relationship instance ID is automatically generated when the relationship instance is saved in the relationship table. Relationship Manager displays this instance ID at the top level of the relationship tree.

Figure 34 shows an example in Relationship Manager of a relationship tree for an identity relationship.

Figure 34. Relationship Manager, relationship tree


You can use Relationship Manager to work on entities at all levels: the relationship instance, participant instance, and attribute levels. For example, you can use Relationship Manager to:

Steps for starting Relationship Manager

Perform one of the following steps to start Relationship Manager:

Relationship Manager starts. At this point it is disconnected from the server; you must connect to an InterChange Server Express instance as described in Steps for connecting Relationship Manager to InterChange Server Express to proceed further.

Figure 35 shows Relationship Manager in a disconnected state.

Figure 35. Relationship Manager


Connecting to and disconnecting from a server

You must connect Relationship Manager to InterChange Server Express to work with relationship instances and data. Follow the instructions in the following sections to connect Relationship Manager to a server and disconnect Relationship Manager from it:

Steps for connecting Relationship Manager to InterChange Server Express

Perform the following steps to connect Relationship Manager to InterChange Server Express:

  1. Click Server > Connect. The Connect to InterChange Server dialog box appears (see Figure 36).

    Figure 36. Connect to InterChange Server Express


  2. Do one of the following to populate the name of the InterChange Server Express instance to which you want to connect in the Server Name field:
  3. Type the user name to interact with the InterChange Server Express instance in the User Name field.
  4. Type the password for the user name supplied in step 3 in the Password field.
  5. If you do not want to have to supply the user name and password each time you have to connect to the InterChange Server Express instance in System Manager then enable the Save user name and password check box.
  6. If you want to open a relationship at this time type the name of the relationship definition in the Relationship field.

    If you do not want to open a relationship at this time you can open it after connecting to the server. For more information, see Steps for opening a relationship.

  7. Click Connect.

    If you connect to InterChange Server Express in Relationship Manager and specify a relationship to open as described in step 6, then Relationship Manager displays the Retrieve Relationship Instances window, described in Steps for retrieving relationship instances.

Steps for disconnecting Relationship Manager from InterChange Server Express

Perform the following step to disconnect Relationship Manager from InterChange Server Express:

Working with relationships in Relationship Manager

After you have started Relationship Manager and connected it to an InterChange Server Express, you can use Relationship Manager to work with relationship data as described in the following sections:

Steps for opening a relationship

Steps for retrieving relationship instances

Steps for creating relationship instances

Steps for deleting relationship instances

Deactivating and activating participants

Steps for copying participants

Steps for loading and unloading business object files

Steps for opening a relationship

Perform the following steps to open a relationship definition in Relationship Manager after it is already connected to the server:

  1. In Relationship Manager, click File > Open.
  2. In the Open Relationship dialog box, select the name of the relationship that you want to open.

    Figure 37 shows the Open Relationship dialog box.

    Figure 37. Opening Relationship dialog box


  3. Click OK.

    When you open a relationship, Relationship Manager displays the Retrieve Relationship Instances window, described in Steps for retrieving relationship instances.

Steps for retrieving relationship instances

Perform the following steps to retrieve relationship instances or to return a count of how many instances there are for a relationship:

  1. In Relationship Manager, click File > Retrieve.
    The Retrieve Relationship Instances dialog box opens (see Figure 38).

    Figure 38. Retrieving Relationship Instances dialog box


  2. You can perform the following operations with the Retrieve Relationship Instances window:

The Retrieve Relationship Instances window is also displayed when you specify a relationship to open when connecting to InterChange Server Express.

Depending on the number of participants in the relationship definition and the number of participant instances in each relationship instance, these retrieval queries may take some time.

Steps for retrieving all instances

Perform the following steps to retrieve the first 500 instances for a relationship:

  1. At the Retrieve Relationship Instances window click Retrieve All.
  2. Click Get Instances.

    Relationship Manager displays the first 500 instances for the relationship.

Steps for retrieving instances by relationship ID

Perform the following steps to retrieve a range of up to 500 instances by relationship ID:

  1. At the Retrieve Relationship Instances window click Retrieve by ID.
  2. Type the ID of the first instance in the range you want to retrieve in the From field.
  3. Type the ID of the last instance in the range you want to retrieve in the To field.
  4. Click Get Instances.

    Relationship Manager displays up to 500 instances in a range of the IDs specified.

Steps for retrieving relationship instances by participant data

Perform the following steps to retrieve a relationship instance based on values for key or non-key attributes of selected participants:

  1. At the Retrieve Relationship Instances window click Retrieve by Value.
  2. Select the participant whose value you want to search on from the Participants list.

    For identity relationships, participant names are followed by the business object definition with which the participant is associated.

    For lookup relationships, participant names are followed by the word "Data".

  3. Type one of the types of values listed in Table 11 in the Value column in the Attributes pane.


    Table 11. Supported values for retrieving relationship instances by participant data

    Value Description
    Participant data The data of the selected participant.

    For example, if the relationship is an identity relationship you would specify the ID of the participant instance that you know to find the relationship instance in which it exists.

    If the relationship is a lookup relationship you would specify the non-key data value of the participant instance.

    %

    Any string of characters. This option is case-sensitive; numbers are included in the character set.

    For example, if %A were specified for a participant that stores abbreviated forms of the names of the United States, the values CA, GA, IA, LA, MA, PA, VA, and WA would be returned.

    _

    Any single character.

    As an example, _00 would retrieve 100, 200, a00, b00, and so forth.

  4. Click Get Instances.

    Relationship Manager displays the first 500 relationship instances that match the specified value.

Steps for returning a count of relationship instances

Perform the following steps to return the number of relationship instances that satisfy a retrieval criteria:

  1. Select the options for the criteria as described in Steps for retrieving all instances, Steps for retrieving instances by relationship ID, or Steps for retrieving relationship instances by participant data
  2. Click Get Count (instead of Get Instances).

Steps for creating relationship instances

Perform the following steps to create a new instance for a relationship:

  1. Create the new relationship instance by doing one of the following:

    Relationship Manager displays the new relationship instance.

    Highlighted at the top of the hierarchal relationship tree, on the entry line with the relationship icon is the placeholder for the relationship instance ID, which displays three question marks (???). After you save the relationship instance or any of its participants, InterChange Server Express automatically generates the new relationship instance ID and Relationship Manager replaces the question marks with this instance ID.

  2. Expand the new relationship instance by clicking on the plus (+) sign next to the ??? placeholder icon.

    The relationship tree displays participant definitions, participant instances, and participant key and non-key attributes beneath the relationship instance in descending order.

  3. Do the following to create a new participant instance in the relationship instance:
    1. In the relationship tree, select the participant definition for which you want to create an instance.
    2. Do one of the following to add an instance for the participant:
      • Right-click a participant definition in the listing and click Add Participant.
      • Click Add Participant on the toolbar.
    3. Expand the new participant instance by clicking the plus (+) sign next to it.
    4. Select the new participant instance.
    5. Click the Value column for the participant instance, then type a value into the cell.
      Note:
      If the Value field for the attribute displays three question marks (???), the participant is managed by InterChange Server Express. You cannot enter values for these participants because InterChange Server Express automatically generates them when you save the relationship instance. The value is the same value as the relationship instance ID.
  4. Do any of the tasks listed in Table 12.

Table 12. Tasks for participant data

Task Action
Save the participant instance. To save the new participant instance, right-click the participant instance and click Save Participant. Relationship Manager saves in the appropriate relationship table the data for this participant. The Modified column for the participant instances displays the date the participant was saved, which is the create date, in this case.
Note:
After the participant data has been saved, it cannot be changed. To change its data, the participant must be deleted and another created.
Add more participant instances. Repeat repeat step 3 in the previous list.
Note:
If you are working with an identity relationship, you cannot create more than one participant instance for a participant definition.
Delete a participant. If necessary, you can delete a saved participant instance by right-clicking the participant instance and selecting Delete Participant. Relationship Manager removes the participant instance from the relationship table. If you do not want to remove the participant instance from the database, use the Deactivate Participant option (see "Deactivating and activating participants"). A deactivated participant retains its instance ID and its values.
Save the relationship instance. Save the relationship instance by performing one of the following tasks:
  • Click File > Save.
  • Right-click the relationship instance and select Save Relationship.
InterChange Server Express generates the relationship instance ID and Relationship Manager replaces the ??? placeholder with this new ID. Relationship Manager updates the modified date on all saved participant instances to this date.
Note:
At least one participant instance and all key attribute data must be created before the relationship instance can be saved.
Save all relationship instances. Click File > Save All. InterChange Server Express generates the relationship instance IDs for any relationship instances that do not have one. Relationship Manager replaces any ??? placeholders with the new IDs. Relationship Manager updates the modified date on all saved participant instances to this date.

Steps for deleting relationship instances

Perform the following steps to delete a relationship instance from the relationship tables:

  1. Select the relationship instance that you want to delete.
  2. Do one of the following in Relationship Manager:

The relationship instance and its data are deleted from the relationship tables for the current relationship.

Deactivating and activating participants

A participant instance can be deactivated, or made inactive. Deactivating a participant instance removes it from the relationship instance and prevents it from displaying in the Relationship Manager window, but its record remains in the relationship table so it can be re-activated in the future.

Steps for deactivating a participant

Perform the following step to deactivate a participant instance:

Steps for activating a participant

Perform the following steps to activate a participant instance:

  1. Select View > Show Deactivated Participants.

    The Deactivated Participants window appears as shown in Figure 39.

    Figure 39. Deactivated Participants window


  2. Select the relationship instance that contains the deactivated participant you want to activate from the list.
  3. Expand the relationship instance until the deactivated participant instances appear in the list.
  4. Right-click the participant instance that you want to reactivate and select Activate.
  5. Click Edit > Refresh.

    The activated participant instance appears in its relationship instance in the Relationship Manager window.

    Note:
    If a participant instance in an identity relationship is deactivated and another participant is added in its place (that is, assigned the same instance ID), the original participant is removed from the Deactivated Participants listing, but remains in the database.

Steps for copying participants

You can create a new participant instance by copying an existing participant instance.

Perform the following steps to copy a participant instance:

  1. In the relationship instance, right-click the participant definition and click Add Participant.
  2. Right-click the participant instance that you want to copy and click Copy Participant.
  3. Right-click the newly created participant instance and click Paste Participant.

Steps for loading and unloading business object files

You can load a business object file of the same type into a participant. Perform the following steps to load a business object data file into a participant:

  1. Right-click the participant instance where you want to load the business object file and click Load Participant with Business Object.

    The Load Participant with Business Object dialog box displays the business object associated with that participant instance, as shown in Figure 40.

    Figure 40. Load Participants with Business Objects dialog box


  2. Click Load.
  3. Navigate to and open the business object file that you want to load.
  4. Click OK.

Note:
Only the first instance of a relationship is loaded if more than one instance exists in the file.

Working with relationship data in Relationship Manager

An important feature of Relationship Manager is the ability to access and manipulate relationship run-time data contained in the relationship tables. The following topics describe how to use Relationship Manager to manipulate and access run-time data:

Steps for searching for participants

Steps for filtering the displayed participants

Steps for cleaning up participants

Steps for printing relationship data

Steps for searching for participants

You can search for participant instances based on different criteria. Depending on how specific your search criteria is, your searches can locate a unique participant instance or a group of participant instances.

Perform the following steps to search for instances by business object:

  1. Select a participant instance in Relationship Manager.
  2. Click Edit > Find Instances by Business Object.

    The Find Instances by Business Object window appears (see Figure 41).

    Figure 41. Find Instances by Business Object dialog box


  3. Type the participant value by which you want to search in the Value cell.
  4. Click OK.

    Relationship Manager displays any matching instances in a dialog box.

  5. Double-click any of the instances in the dialog box to navigate to and select the instance.

Perform the following steps to search for instances by data:

  1. Select a participant instance in Relationship Manager.
  2. Click Edit > Find Instances by Data.

    Relationship Manager displays the Find Instances by Data dialog box, as shown in Figure 42.

    Figure 42. Find Instances by Data dialog box


  3. Type the participant value by which you want to search in the Enter the data cell.
  4. Click OK.

    Relationship Manager displays any matching instances in a dialog box.

  5. Double-click any of the instances in the dialog box to navigate to and select the instance.

Steps for filtering the displayed participants

You can filter the participants to only display those created or modified between certain dates.

Perform the following steps to filter the displayed participants:

  1. Select a participant in Relationship Manager.
  2. Click View > Filter.

    The Filter dialog box appears, as shown in Figure 43.

    Figure 43. Filter dialog box


  3. In the Filter dialog box, enter the earliest date of creation or modification for the participant in the from field and the latest date of creation or modification for the participant in the to field.
  4. Select the Include inactive participants as well check box if you want to include inactive participants in the results.
  5. Click OK.

    Relationship Manager displays the history of activity for the filtered interval in the Filter Results dialog box. The dialog box includes inactive participants if Include inactive participants as well is selected. Figure 44 shows the Filter Results dialog box.

    Figure 44. Filter Results dialog box


Steps for cleaning up participants

You can remove incorrect participant information caused by inconsistent or corrupt data from the source application or generic object.

Perform the following steps to clean up participants in System Manager:

  1. Select a participant in Relationship Manager.
  2. Click Edit > Clean Up Participants.

    The Clean Up Participants dialog box appears, as shown in Figure 45.

    Figure 45. Clean Up Participants dialog box


  3. In the Clean Up Participants dialog box, enter the date to which you want to revert the participant values to in the Clean up from field.
  4. Click OK.

    All participant adds, deactivations, and activations since that point in time are erased from the database. A participant that has been deleted or whose value has been modified cannot be cleaned up.

Steps for printing relationship data

Relationship Manager allows you to print information about a relationship's run-time data. It creates a tree representation of the run-time data, much like the data appears in the tool's main window. The print command in Relationship Manager sends the current contents of the relationship tree in the main window to the printer.

Perform the following steps to print relationship run-time data:

  1. Expand the relationship tree of Relationship Manager so that the information you want to print is displayed.
  2. If you want to print only a portion of the relationship instances, designate those instances by selecting them.
  3. Print relationship run-time data in any of the following ways:
  4. The Print Relationship Instances dialog box appears. Select either all instances or selected instances, then click OK.

Copyright IBM Corp. 2004