Filtering by Inclusion Property

You can specify that a node will be included or excluded from a subscription by configuring an inclusion property on the node.

You can use this inclusion property to, for example, add a node in a source viewpoint without immediately adding it to the target viewpoints. Then, when you are ready to add the node to the target viewpoints you can change the inclusion property value in the source viewpoint to generate the subscription request actions to add that node to any subscribing target viewpoints.

Note:

The inclusion property must be a node level property.

An inclusion property is a Boolean or List data type property that controls whether a node in a source viewpoint gets sent to the target viewpoint as part of a subscription.

• If the inclusion property is a Boolean data type, the node is added to the target viewpoints when the Boolean value is True, and removed from target viewpoints when the value is False. Typically, you use a Boolean inclusion property when there is a single subscribing target viewpoint and you want to specify whether or not to include a node in that subscription.
• If the inclusion property is a List data type, you must specify the inclusion value (either by entering the value or selecting the value from an Allowed Values list). Use a List data type property when you have multiple subscribing target viewpoints and you want to specify which target viewpoints the node should be included in subscriptions for.

When the inclusion property is set in the source viewpoint to include the node (that is, has a value of True for Boolean or contains the inclusion value for a list), request actions for the node are generated for the target viewpoint by the subscription. If the node does not already exist in the target viewpoint, it is added or inserted.

When the inclusion property is set in the source viewpoint to exclude a node (that is, has a value of False for Boolean or does not contain the inclusion value for a list), the node is removed or deleted if it exists in the target viewpoint. If it does not exist, no request actions are generated for the excluded node.

Best Practice

If you want to retain property values and child relationships for nodes that you are excluding from the target viewpoint, it is a best practice to remove the Delete action from the Included Actions filter on the subscription so that the node is removed only. See Filtering by Actions.

Considerations

• You can configure an inclusion property filter using any Boolean or List data type property from any node type in the source viewpoint.

  Note:

  You can configure an existing property as an inclusion property, or you can create a new property to use as the inclusion property for this subscription. See Creating Properties Manually.
• The inclusion property can have a Default Type of None or Specified. The Specified default type can be useful in these scenarios:
  • By default, you want to include all nodes in a subscription, and you will explicitly specify which nodes you do not want to include. You can set the default value to include the node (has a value of True for Boolean or contains the inclusion value for a list) and then change the property only for the nodes that you want to exclude.
  • By default, you want to exclude all nodes in a subscription, and you will explicitly specify which nodes you want to include. You can set the default value to exclude the node (has a value of False for Boolean or does not contain the inclusion value for a list) and then change the property only for the nodes that you want to include.

  If you have a default type of None, you will have to specify the inclusion property value for every node.

• The Default Type cannot be Derived or Inherited. After you designate a property as an inclusion property, you cannot change that property's default type to be either derived or inherited.

• Node expression, top node, and action filters are applied to the generated request actions. For example, if the inclusion property on a node is set to include but the node is under a top node that has been filtered out of the subscription, request actions are not generated for that node.

• Some request actions in the source viewpoint are translated to equivalent actions in the target viewpoint:

  • If you modify the inclusion value in the source viewpoint from False to True (or to contain the inclusion value, for a list), the node is added (or inserted, in a hierarchy set) in the target viewpoint if it doesn't already exist.

  • If you modify the inclusion value in the source viewpoint from True to False (or not to contain the inclusion value, for a list), the node is deleted (or removed, in a hierarchy set) if it exists in the target viewpoint.

  • If you do not modify the inclusion value in the source viewpoint, request actions that you perform in the source viewpoint are propagated to the target viewpoint if the inclusion property is set to True (or to contain the inclusion value, for a list).

• For shared nodes when the target viewpoint is a hierarchy:
  • If the inclusion property is updated to either include or exclude a node in the source viewpoint, request actions are generated for all instances of the node.
  • If the inclusion property is not updated and the node is set to be included, request actions are generated only for the instances where the action was performed.
  • If the inclusion property is not updated and the node is set to be excluded, request actions are not generated for any instance of the node.

  For example, suppose you have a shared node under parents A, B, and C in the source viewpoint.

  • If you update the inclusion property to include a node under parent A in the source viewpoint, request actions are generated to add the node under parent A and insert the node under parents B and C in the target viewpoint. Similarly, if you update the inclusion property to exclude a node under parent A in the source viewpoint, request actions are generated to delete the node under parent A and remove it from parents B and C in the target viewpoint.
  • If you do not update the inclusion property and the node is set to be included, request actions are generated only for the instance of the node where you performed the action. So if you edited a property for the node under parent B in the source viewpoint, a request action is generated to modify that property only for the node under parent B in the target viewpoint.
  • If you do not update the inclusion property and the node is set to be excluded, request actions are not generated for the nodes no matter which instance in the source viewpoint you perform an action on.

Tip:

When you have multiple subscribing viewpoints, you can use a List data type inclusion property if there is only one user, such as a Service Administrator, who will determine which viewpoints will receive which nodes. If there are different users who each determine whether or not a property is sent to the viewpoint that they administer, you can set up multiple Boolean data type inclusion properties and use property-level data access to control which users can view or edit the Boolean property for their viewpoint.

For example, you can configure data access so that only the Planning administrator is able to edit the "Include for Planning?" property, and only the Consolidation administrator is able to edit the "Include for Consolidation?" property in the source viewpoint. See Boolean Data Type Inclusion Property Example in Inclusion Property Examples.

Note:

If you are already using a node condition to filter nodes out of subscriptions based on the value of a Boolean or List data type node level property (see Defining Node Conditions), you should replace the node condition filter with an inclusion property filter.

If you are using a node condition filter on a relationship level property, you should keep the existing node condition filter because you cannot create an inclusion property filter on a relationship level property.

Configuring the Inclusion Property

1. Inspect the viewpoint that contains the subscription that you want to configure the inclusion property for, and click the Subscriptions tab.
2. Create a new subscription or edit an existing subscription. See Subscribing to Viewpoints.
3. On the Filters tab, click Edit.
4. From the Inclusion Property drop down menu, select a property to configure as the inclusion property. Only node properties with the Boolean or List data type are available to be selected.
5. If the property that you selected has the List data type, in Inclusion Value enter an inclusion value (or select the value if the property uses Allowed Values).

   Note:

   If the property has application or node type overrides for Allowed Values, all of the allowed values from all overrides are available to be selected as inclusion values.
6. Click Save.