Overview

Overview of Rules

Rules consist of code that is written in Visual Basic.Net (VB.Net), a programming language that is compatible with the language in which APM is written. If you have sufficient knowledge of writing VB.Net code, you can write rule code to be executed when certain changes occur in the APM database. You can write family-level or field-level rules.

As an alternative to family-level rules, you can use family policies to configure certain actions to occur when a record changes in the APM database. Family policies are created in a user interface where knowledge of Visual Basic.Net (VB.Net) is not required.

Note: For a single family, you can write family-level rules or family policies, not both. You can, however, use the Baseline Rule node in a family policy to execute any existing APM baseline rules that correspond to the policy’s family and trigger. You can also use field-level rules and family policies for the same family.

Rules Workflow

Note: This workflow assumes that the APM Rules Editor extension in Microsoft has already been installed.

This workflow provides the basic, high-level steps for using this module. The steps and links in this workflow do not necessarily reference every possible procedure.

  1. If you want to configure a family-level rule for a family, specify in Configuration Manager that family-level rules should be used for that family.
  2. Open the Rules Editor, and then access either a family rule project or the Rules Library.
  3. If you accessed the Rules Library, then you can add a folder to the library.
  4. Create a new Rules Library rule project.
  5. Add a reference to the project.

About Family Rule Projects

A family rule project is an organizational unit that provides the coding infrastructure within which the rules for that family will be written and stored.

  • For baseline families, a family rule project exists for any family for which family-level or field-level rules have been defined within that specific family. For baseline subfamilies that inherit all their behaviors from higher-level families, a family rule project will not exist.
  • For custom families, the family rule project is created the first time that you access the family-level or field-level rules for the family.

More Details

Family rules can be viewed and managed in the APM Rules Editor. When you open the rule project for a family, the family rule project will be selected by default. Below the project name is a list of all the items that are currently included in the project.

By default, the content of the project will consist of references and files. Each family rule project contains a file for the family itself and a file for each field within the family. A file will be created for each field that is defined directly within that family and each field that is spread down from a family where the field can be customized at the sublevel.

As you add fields to a family, new files will be added to the family rule project. You can select any file to view and modify the code that is stored within it.

Within each file, a class is defined for the corresponding family or field. Each class serves as the organizational unit within which actual family-level and field-level customization code exists. The name of the file matches the name of the class defined within it, which in turn corresponds to the field ID or family ID (i.e., not the family or field caption).

Note: Changing the ID for a field when the field already has a VB.Net file will cause APM to create a new file based on the new ID. The old file will not be deleted but will be disconnected from the field.

You can open multiple rule projects at a time. When you do so, each rule project will appear as a root-level entry in the Solution Explorer pane.

When you access the family rule project for a baseline APM family, the corresponding baseline Rules Library project will also appear in the Solution Explorer pane. The baseline Rules Library project has the same name as the family rule project with _Base appended to it.

You cannot modify the baseline Rules Library project, but it is displayed so that you can easily view and debug the baseline rule code to understand the baseline family and field rules.

Configure a Family to Use Family-Level Rules

About This Task

If you want to configure a family-level rule for a family, you first must specify in Configuration Manager that family-level rules should be used for that family.

Important: For a single family, you can use family-level rules or family policies, not both.

Procedure

  1. Access the Configuration Manager page, and then select Data Configuration.

    The Data Configuration page appears.

  2. Select Family Management.

    The Family Management page appears.

  3. Select the family for which you want to use family-level rules.

    The workspace for the selected family appears.

  4. In the workspace, select Rules and Policies tab.

    The Rules and Policies section appears.

  5. Select the VB Rules radio button, and then select .
    Important: If Family Policies was previously selected, VB Rules will be used instead of any configured family policies.

What To Do Next

Access the APM Rules Editor

Before You Begin

If you want to configure a family-level rule for a family, specify in Configuration Manager that family-level rules should be used for that family.

Procedure

  1. On the APM Server, access Microsoft Visual Studio.
  2. On the Tools menu, select APM Rules Editor.

    The APM Rule Explorer pane appears, prompting you to log in.

  3. In the User Name box, enter a user name that can log in to the data source whose rules you want to manage.
  4. In the Password box, enter the password that is associated with the specified Security User.
  5. In the Data Sources list, select the data source whose rules you want to manage.
  6. Select Log In.

    The APM Rule Explorer pane displays the list of entity families.

Access a Family Rule Project

Procedure

  1. Access the APM Rules Editor.
  2. Select Families or Relationships.
  3. Select the family whose rule project you want to open.
    Note: Only green folders contain rule projects.

    The Solution Explorer pane appears, displaying the family rule project.