Visier Multi-Subject Rules Language

Use the Visier Multi-Subject Rules Language to validate data or perform additional transformations on already-modified data.

Overview

Use the Visier Multi-Subject Rules Language to validate data or perform additional transformations on already-modified data. For more information, see Multi-Subject Rules.

Multi-subject rules use the following format.

Copy 
call RULENAME (
    ARG1, 
    ARG2, 
    …
)
  • call: Instructs Visier to call the rule.
  • RULENAME: Specifies the rule to use. Each rule executes different logic against the arguments in the formula. For more information about the available rules, see Rules.
  • ARG1, ARG2: Specifies the objects, such as subjects or properties, to validate. For more information about possible arguments, see Arguments.

Multi-subject rules apply to multiple subjects, so each object must use its qualified name in the rule. For example, the properties Employee.EmployeeID or Applicant.First_Name and the leveled dimension Employee.Location.City.

Note: In multi-subject rules, a subject can be:

  • A subject analytic object, such as Employee or Applicant.
  • A parent child hierarchy, such as a parent-child dimension like Supervisory Hierarchy.
  • A multi-value data table, such as Budgeted Compensation.

For examples of multi-subject rules, see Multi-Subject Rules Examples.

Rules

You can use the following rules in your multi-subject rule formulas.

adjustProfile

Extends the target subject's profile to correspond to the source subject's profile. Matches source and target subjects by their subject IDs.

Target subject profiles do not extend if the profile of the source falls outside the profile of the target. Profiles are only moved within their valid ranges.

Caution: The source subject and target subject must have the same time granularity. For more information, see Time granularity.

Syntax

Copy 
call adjustProfile(
    sourceSubject,
    targetSubject,
    keyMapping,
    useNonActiveAttribute,
    adjustToTermination
)
  • sourceSubject: The subject whose event stream is used to adjust the target subject's profile event stream. The source subject's profile is not modified by this rule.
  • targetSubject: The subject whose profiles are adjusted based on the source subject. The target subject's profile may be modified by this rule.

  • keyMapping (optional): Controls how the source subject key is translated to the target subject key. Optionally specify the property that represents the ID of the target subject or use keyDropAfter to transform the keys so that they match. The default is to use the same key to access both subject members, such as EmployeeID.

    Tip: If the keyMapping isn't usable and you need to map subjects using something else, see profileAdjustmentLinkAttribute.

  • useNonActiveAttribute (optional, Boolean, default: false): If true, the rule considers the subject's non-active attribute and doesn't extend the target subject's profile beyond periods where the source subject is active.
  • adjustToTermination (optional, Boolean, default: false): If true, the rule pulls back the target subject's profile changes to match the source subject's first termination within the valid range, if available. This modifies the target subject's profile change events; it does not modify termination.

Let's say your organization sends temporal data to Visier once a month. Your employee start data is always recorded on the day it occurs, such as January 15, but budgeted compensation data is recorded as of the end of the month, such as January 31. Use adjustProfile to associate budgeted compensation data with employee data so that the budgeted compensation profile extends back to January 15.

Copy
Extends Budgeted Compensation profiles to their corresponding Employee profiles by matching EmployeeID to Compensation_Type. Drops any characters after an underscore in EmployeeID and Compensation_Type to form a composite key; for example, 1234_EMP becomes 1234.
call adjustProfile(
    Employee, 
    Employee.Employee_Budgeted_Compensation, 
    keyDropAfter("_")
)

adjustRecursiveReference

Adjusts a profile's start and end dates if the object references itself, such as a parent-child dimension. Extends the start and end dates of the parent forward and backward to align with the start and end dates of its children. This rule makes the parent profile valid at all times that the child is valid.

When adjustRecursiveReference pulls a profile start date forwards, it also pulls any profile change events forward that happen on the same date as the profile start event to make sure the adjusted profile has the correct profile values.

Tip: Use adjustRecursiveReference with rules that extend the start or end dates of some, but not all, members in the subject and should extend the member's parent profiles too. For example, use this rule after the adjustProfile rule to make sure any member profile adjustments made by adjustProfile apply to their parents as well.

Syntax

Copy 
call adjustRecursiveReference(
    targetSubject,
    targetSubject.RecursiveReferenceProperty,
    maxDepth
)
  • targetSubject: The subject to adjust. Must have self-references, such as how Organization Hierarchy references itself in the ParentOrgID property.
  • targetSubject.RecursiveReferenceProperty: The self-reference property in targetSubject, such as ParentOrgID.
  • maxDepth (optional, integer, default: 20): The lowest level of the hierarchy to check parent-child relationships. If the hierarchy has more levels than maxDepth, the rule may not adjust all parents.

Let's say that there are organizations in your Organization Hierarchy data that existed before their parent organization. This rule pulls back the parent organization's start date so they exist at any time that their child organizations are valid.

Copy
Extends parent organizations in Organization_Hierarchy according to the ParentOrgID property. Uses the default max hierarchy depth of 20.
call adjustRecursiveReference(
    Organization_Hierarchy, 
    Organization_Hierarchy.ParentOrgID
)

In another scenario, let's say you're using adjustProfile and adjustRecursiveReference together to achieve the following:

  • adjustProfile extends the start dates of organizations in the Organization_Hierarchy to match the start dates of employees in the Employee subject. Employees are matched to organizations using keys that are the same after dropping any characters after an underscore.
  • adjustRecursiveReference then extends the start dates of all organizations in the Organization_Hierarchy to match the start dates of their child organizations up to a maximum hierarchy depth of 25.
Copy
First rule using adjustProfile.
call adjustProfile(
    Employee, 
    Organization_Hierarchy, 
    keyDropAfter("_")
)
Copy
Second rule using adjustRecursiveReference.
call adjustRecursiveReference(
    Organization_Hierarchy, 
    Organization_Hierarchy.ParentOrgID, 
    25
)

extendedStateReconciliationRule

Reconciles the target subject's state based on a reference subject's state with the option to specify a state after the reference subject's last termination state. For example, if a Requisition is closed, all Applicants should also be closed.

Tip: For non-extended state reconciliation, see stateReconciliationRule.

Syntax

Copy 
call extendedStateReconciliationRule(
    referenceSubject,
    referenceProperty,
    targetSubject,
    keyProperty,
    targetProperty,
    stateMap,
    referenceStateAfterLastTermination,
    gracePeriod
)
  • referenceSubject: The subject to use to reconcile the target subject's state. The reference subject is not modified by this rule.
  • referenceProperty: The reference subject's property that determines the state against which to validate the target subject's state. The reference property is not modified by this rule.

    For example, if Applicant is the target subject, and Requisition is the reference subject, then Requisition.Requisition_Status is the reference property because its value is the state you want to reconcile against.

  • targetSubject: The subject whose state you want to reconcile. This subject's event stream may be modified by this rule.
  • keyProperty: The target subject's property that references the reference subject member's ID.

    For example, if Applicant is the target subject and Requisition is the reference subject, then Applicant.RequisitionID is the key property because it references Requisition's subject member ID.

  • targetProperty: The target subject's property that determines the state to validate against the reference property's state. The target property value may be modified by this rule.

    For example, if Applicant is the target subject, Requisition is the reference subject, and Requisition.Requisition_Status is the reference property, then Applicant.Applicant_Status is the target property because its value is the state you want to reconcile.

  • stateMap (optional): The reference property values against which to validate the target subject and the specifications for how to reconcile the target subject's states. Also specifies the values to change invalid target property values to. In stateMap, only map the values that require validation.

    The state map format is:

    Copy
    {
        "referenceProperty value" -> { { "targetProperty value valid for this referenceProperty value", "another valid targetProperty value" } -> "targetProperty value to use if existing value is not valid" }
    }
  • referenceStateAfterLastTermination (optional): The reference property value after the reference subject's last profile termination. This ensures the target subject's state changes if the reference subject was terminated, but their reference property doesn't reflect the termination. If not specified, the rule behaves the same as stateReconciliationRule.
  • gracePeriod (optional, default: 0): The period that the target subject's state can be invalid without being corrected by the rule with respect to the reference subject's state changes. During the grace period, the target subject's state is frozen and is unchanged by the rule. After the grace period, the target subject is reconciled to a valid state if the target subject is not valid. The grace period:
    • Is granular to 1 day.
    • Is inclusive.
    • Starts at each change of the reference subject's state, not the target subject's state.

Let's say you want to reconcile the states between Employee and Learning. When an Employee is inactive, the employee's associated Learning must also be in an inactive state (Cancelled, Abandoned, or No Show). This rule changes any active learning records to inactive if there is no active employee associated with the learning record.

If the Learning is not in one of the specified states, the rule changes the Learning status to abandoned (System Abandoned), as specified in stateMap. In this example, the reference subject is Employee and the target subject is Learning. Additionally, this rule specifies the Inactive state in referenceStateAfterLastTermination to close any learning activities after an employee profile is terminated but their Employee_Status is not inactive.

This example does not specify a grace period, so it uses the default of 0 days.

Copy
Reconciles Learning's state to Employee's state with no grace period. Specifies Inactive as the reference property's state after last termination.
call extendedStateReconciliationRule(
    Employee,
    Employee.Employee_Status
    Learning,
    Learning.Employee_ID,
    Learning.Learning_Status,
    {  
        "Inactive" → { { "Cancelled", "Abandoned", "No Show" } -> "System Abandoned" }
    },
    "Inactive"
)

hasChildMemberRule

Checks whether a subject member has any children. The subject's associated parent-child dimension specifies the parent-child relationship. For example, if you want to know whether an employee has any direct reports, you can use Employee.Manager_Status and the Organization_Hierarchy parent-child dimension in this rule.

Syntax

Copy 
call hasChildMemberRule(
    populationSubject,
    orgIDProperty,
    statusProperty,
    activeChildren,
    parentChildSubject,
    orgHeadIDProperty
)
  • populationSubject: The subject to check for children.
  • orgIDProperty: The subject attribute that references the parent-child dimension.
  • statusProperty: The subject attribute that identifies whether the subject member has any children.
  • activeChildren: If true, the rule only considers active children. If false, the rule considers active and inactive children. Default is true.
  • parentChildSubject: The parent-child dimension that specifies the subject's parent-child relationships.
  • orgHeadIDProperty: The parent-child dimension's attribute that identifies the parent in a parent-child relationship.

Let's say you want to know if an employee has any direct reports, regardless of whether the children are active or inactive. In this rule, the rule returns a positive Employee.Manager_Status value if the employee has direct reports, otherwise it returns a negative Employee.Manager_Status value. This creates Employee.Manager_Status if the employee has at least one direct report. This is useful if your organization isn't able to provide Employee.Manager_Status directly or if the data is not accurate.

Copy
Checks whether an employee has any active or inactive direct reports.
call hasChildMemberRule(
    Employee, 
    Employee.Organization_ID, 
    Employee.Manager_Status, 
    false, 
    Organization_Hierarchy, 
    Organization_Hierarchy.Organization_Head
)

In another scenario, let's say you want to know if an employee has any active direct reports. In this rule, the rule returns a positive Employee.Manager_Status value if the employee has active direct reports, otherwise it returns a negative Employee.Manager_Status value.

Copy
Checks whether an employee has any active direct reports.
call hasChildMemberRule(
    Employee, 
    Employee.Organization_ID, 
    Employee.Manager_Status, 
    true, 
    Organization_Hierarchy, 
    Organization_Hierarchy.Organization_Head
)

Let's say you want to set the Employee.Manager_Status value based on Supervisory_Hierarchy. In this example, you can use a combination of multi-subject rules to achieve your goal.

The first rule uses referenceRule to check the validity of references between Employee and Supervisory_Hierarchy. For invalid references, this rule creates Unknown values. Unknowns are required for troubleshooting your data.

Copy
Checks reference validity and creates Unknown values.
call referenceRule(
    Employee, 
    Employee.Direct_Manager, 
    Supervisory_Hierarchy
)

The second rule uses pcHierarchyMultiReferencePruningRule to remove employees without direct reports. You want to remove employees without direct reports because they are not managers.

Copy
Removes employees without direct reports.
call pcHierarchyMultiReferencePruningRule(
    Supervisory_Hierarchy, 
    Supervisory_Hierarchy.Manager, 
    {
        Employee -> Employee.Direct_Manager
    }, 
    {
        "-999"
    }
)

The third rule uses hasChildMemberRule to set Employee.Manager_Status if the employee has active direct reports.

Copy
Sets Manager_Status for employees who have active direct reports.
call hasChildMemberRule(
    Employee, 
    Employee.Direct_Manager, 
    Employee.Manager_Status, 
    true, 
    Supervisory_Hierarchy,
    Supervisory_Hierarchy.Supervisory_Head
)

hasRequiredChildMemberRule

Checks whether a parent subject member's children have certain attribute values. For example, you can use this rule to check whether a manager's direct reports have a Gender value of F.

Syntax

Copy 
call hasRequiredChildMemberRule(
    populationSubject,
    orgIDProperty,
    statusProperty,
    attributeValueMap,
    parentChildSubject,
    orgHeadIDProperty
)
  • populationSubject: The subject in which to check the parent-child attributes.
  • orgIDProperty: The subject attribute that references the parent-child dimension.
  • statusProperty: The subject attribute that identifies whether the subject member has any children.
  • attributeValueMap: The subject's property value to check for the parent's children.

    The attribute value map format is:

    Copy
    { 
        populationSubjectProperty -> propertyValue 
    }
  • parentChildSubject: The parent-child dimension that specifies the subject's parent-child relationships.
  • orgHeadIDProperty: The parent-child dimension's attribute that identifies the parent in a parent-child relationship.

Let's say you want to know if any direct managers have direct reports who are women, where women is defined in the data as F. In this rule, the rule returns a positive Employee.Manager_Status value if the employee has women direct reports who are active employees, otherwise it returns a negative Employee.Manager_Status value. This creates Employee.Manager_Status if the employee has at least one direct report who is a woman and an active employee. This is useful if your organization isn't able to provide Employee.Manager_Status directly or if the data is not accurate.

Copy
Checks whether the direct manager has direct reports whose Employee.Gender is F.
call hasRequiredChildMemberRule(
    Employee, 
    Employee.Organization_ID, 
    Employee.Manager_Status, 
    { 
        Employee.Gender -> "F", 
        Employee.NonActiveEmployee -> 0
    }, 
    Organization_Hierarchy, 
    Organization_Hierarchy.Organization_HeadID
)

In the previous example, hasRequiredChildMemberRule selects employees who are women and active employees. In another scenario, let's say your direct report criteria is an OR statement, not AND, such as women or minorities. You can use hasRequiredChildMemberRule to create Employee.Manager_Status, but you must first create a property in the Employee mapping with the extraction formula if (column("Gender") = "F" or column("Minority") = "Yes") "Yes" else "No". Then, you can identify the property in the rule. In this example, the mapping property is Employee.Diverse.

Copy
Checks whether the direct manager has direct reports whose Employee.Diverse value is Yes.
call hasRequiredChildMemberRule(
    Employee, 
    Employee.Organization_ID, 
    Employee.Manager_Status, 
    { 
        Employee.Diverse -> Yes
    }, 
    Organization_Hierarchy, 
    Organization_Hierarchy.Organization_HeadID
)

orgBackwardExtensionRule

Captures an as-is organization hierarchy by taking the organization hierarchy's structure as-was on the date boundary (or the end of time if you don't specify dateBoundary) and projects the hierarchy backward to the start of the application. The rule displays the current hierarchy as if it had existed forever in the generated form. For more information about as-is and as-was hierarchies, see Understanding the Behavior of Organization Hierarchies Across History.

Terminated organization members are revived from the terminated date backward. You can add a prefix or suffix to inactive organization members to identify them as inactive.

Syntax

Copy 
call orgBackwardExtensionRule(
    parentChildSubject, 
    nameProperty, 
    prefix, 
    suffix, 
    dateBoundary
)
  • parentChildSubject: The parent-child dimension on which to execute the rule.
  • nameProperty: The property that identifies the parent-child dimension organization.
  • prefix (optional): A string to add before an inactive organization's name.
  • suffix (optional): A string to add after an inactive organization's name.
  • dateBoundary (optional, default: 9999, 12, 31): The date at which to capture the organization hierarchy and project it forward.

Let's say you want take the Organization_Hierarchy structure as of 2022-01-01 and project it backward to the beginning of time in your application. This rule doesn't modify any hierarchy changes beyond 2022-01-01. Additionally, this rule adds the prefix Inactive to any inactive organizations' names.

Copy
Captures the Organization_Hierarchy structure and 2022-01-01 and projects it backward to the beginning of time. Adds the prefix Inactive to any inactive organizations' names.
call orgBackwardExtensionRule(
    Organization_Hierarchy, 
    Organization_Hierarchy.Organization_Name, 
    "Inactive",
    date(2022, 1, 1)
)

orgForwardExtensionRule

Captures an as-is organization hierarchy by taking the organization hierarchy's structure as-was on the date boundary (or the end of time if you don't specify dateBoundary) and projects the hierarchy forward to the end of the application. The rule displays the current hierarchy as if it will exist forever (or until the specified dateBoundary) in the generated form. This is useful if you want to filter by an old organization hierarchy.

If an organization member was terminated after the specified dateBoundary, the organization member is extended from the dateBoundary date forward. You can add a prefix or suffix to inactive organization members to identify them as inactive.

Syntax

Copy 
call orgForwardExtensionRule(
    parentChildSubject, 
    nameProperty, 
    dateBoundary,
    prefix, 
    suffix
)
  • parentChildSubject: The parent-child dimension on which to execute the rule.
  • nameProperty: The property that identifies the parent-child dimension organization.
  • dateBoundary (optional, default: 9999, 12, 31): The date from which to capture the organization hierarchy and project it backward.
  • prefix (optional): A string to add before an inactive organization's name.
  • suffix (optional): A string to add after an inactive organization's name.

Let's say you want capture the Organization_Hierarchy structure as of 2022-01-01 and project it forward to the end of time in your application. This rule doesn't modify any hierarchies terminated before 2022-01-01. Additionally, this rule adds the suffix Inactive to any inactive organizations' names.

Copy
Captures the Organization_Hierarchy structure and 2022-01-01 and projects it backward to the beginning of time. Adds the prefix Inactive to any inactive organizations' names.
call orgForwardExtensionRule(
    Organization_Hierarchy, 
    Organization_Hierarchy.Organization_Name, 
    date(2022, 1, 1),
    "",
    "Inactive"
)

parentChildrenAttributeValueDifferenceRule

Checks whether a specific attribute for a parent is different from any of its children. For example, you can use this rule to check whether a manager's direct reports are at a different location than the manager.

Syntax

Copy 
call parentChildrenAttributeValueDifferenceRule(
    populationSubject,
    orgIDProperty,
    infoProperty,
    statusProperty,
    parentChildSubject,
    orgHeadIDProperty,
    useNonActiveAttribute
)
  • populationSubject: The subject in which to find parent-child attribute differences.
  • orgIDProperty: The subject attribute that references the parent-child dimension.
  • statusProperty: The subject attribute to compare between the parent and children.
  • infoProperty: The subject attribute that the rule uses to show if there is a difference between attribute values. For example, you can use Employee.Manager_Status to identify whether a manager's direct reports are all at the same location as the manager, some are at a different location, or the employee is not a manager.
  • parentChildSubject: The parent-child dimension on which to execute the rule.
  • orgHeadIDProperty: The parent-child dimension's attribute that identifies the parent in a parent-child relationship.
  • useNonActiveAttribute (optional, Boolean, default: false): If true, the rule only considers active children. If false, the rule considers active and inactive children. Default is false.

Let's say you want to know if any managers have any direct reports at a different location than the manager's location. In this example, the rule returns a positive Employee.Manager_Status value if all direct reports are local. If any of the manager's direct reports are in a different location than the manager, the Employee.Manager_Status is negative. If the manager has no direct reports, the Employee.Manager_Status is None.

Copy
Checks whether managers have any direct reports at a different location than the manager's location for active and inactive children.
call parentChildrenAttributeValueDifferenceRule(
    Employee,
    Employee.Organization_ID,
    Employee.Location,
    Employee.Manager_Status,
    Organization_Hierarchy,
    Organization_Hierarchy.Organization_HeadID
)

pcHierarchyMultiReferencePruningRule

Removes a level member from the available data if there are no references to that member in the dimension for a given time period, such as having no employees in a particular organization. If a parent level member and its child both have no references, pruning removes both level members. Pruning reflects your data more accurately because it only shows level members that have members during the selected time period. Pruning can optionally exclude periods where employees were nonactive. This is useful to clean up messy hierarchies and reduce the number of filter options. For more information about pruning, see Turn on pruning.

Syntax

Copy 
call pcHierarchyMultiReferencePruningRule(
    subjectToPrune, 
    parentProperty, 
    populationSubjectMap, 
    excludedIDs, 
    nonActivePropertyMap, 
    persistentFlagConfig
)
  • subjectToPrune: The subject in which to remove hierarchies that have no members.
  • parentProperty: The parent-child dimension's attribute that identifies the parent in a parent-child relationship.
  • populationSubjectMap: The properties that reference the hierarchy, such as Employee.Organization_ID and Applicant.Organization_ID. All properties in populationSubjectMap must have at least one member that references the hierarchy member. If any of the property members do no reference the hierarchy member, the hierarchy member is pruned from the hierarchy.

    The population subject map format is:

    { 
        subject -> property,
        subject -> property,
        ...
    }
  • excludedIDs (optional): The parent-child dimension members IDs to skip during validation. Default is to validate all IDs. Use excludedIDs to manually bypass the rule for hierarchy members that have no incoming references but you still want to display in Visier.
  • nonActiveProperty (optional): The property that indicates whether or not the member is active. If not specified, the rule checks all active and nonactive members.

    The nonactive property map format is:

    Copy
    { 
        subject -> property 
    }
  • persistentFlagConfig (optional): Indicates whether the hierarchy member can be pruned. Default is to allow pruning of any hierarchy member.

    The persistent flag format is:

    Copy
    intFlag(subjectToPruneProperty, flagOnValue)

Let's say you want to prune Organization_Hierarchy members from the hierarchy if there are no employees or applicants that reference the Organization_Hierarchy member or its child member.

Copy
Prunes Organization_Hierarchy members from the hierarchy if there are no employees or applicants that reference the Organization_Hierarchy member or its child member.
call pcHierarchyMultiReferencePruningRule(
    Organization_Hierarchy,
    Organization_Hierarchy.Parent_Organization_ID,
    { 
        Employee -> Employee.Organization_ID, 
        Applicant -> Applicant.Organization_ID 
    }
)

In another scenario, let's say you want to prune Organization_Hierarchy members from the hierarchy if there are no employees or applicants that reference the Organization_Hierarchy member or its child member, except for the OrgIDA and OrgIDB hierarchy members, which should never be pruned.

Copy
Prunes Organization_Hierarchy members from the hierarchy if there are no employees or applicants that reference the Organization_Hierarchy member or its child member. Do not prune the OrgIDA and OrgIDB hierarchy members.
call pcHierarchyMultiReferencePruningRule(
    Organization_Hierarchy,
    Organization_Hierarchy.Parent_Organization_ID,
    { 
        Employee -> Employee.Organization_ID, 
        Applicant -> Applicant.OrgID 
    },
    { 
        "OrgIDA", 
        "OrgIDB" 
    }
)

In another scenario, let's say you want to prune Organization_Hierarchy members from the hierarchy if there are no employees or requisitions that reference the Organization_Hierarchy member or its child member, except for the -1 and -999 hierarchy members, which should never be pruned. In this example, the rule specifies a nonactive property, so it only considers active references to the hierarchy member.

Copy
Prunes Organization_Hierarchy members from the hierarchy if there are no active employees or requisitions that reference the Organization_Hierarchy member or its child member. Do not prune the -1 and -999 hierarchy members. 
call pcHierarchyMultiReferencePruningRule(
    Organization_Hierarchy,
    Organization_Hierarchy.Parent_Organization_ID,
    { 
        Employee -> Employee.Organization_ID, 
        Requisition -> Requisition.Organization_ID 
    },
    { 
        "-1", 
        "-999" 
    }, 
    { 
        Employee -> Employee.NonActiveAttribute 
    }
)

In another scenario, let's say you want to prune Organization_Hierarchy members from the hierarchy if there are no employees or applicants that reference the Organization_Hierarchy member or its child member. In this example, the rule specifies a persistentFlagConfig, so it will not prune the hierarchy member if its persistent attribute is 1.

Copy
Prunes Organization_Hierarchy members from the hierarchy if there are no employees or applicants that reference the Organization_Hierarchy member or its child member and if its persistent attribute is not 1.
call pcHierarchyMultiReferencePruningRule(
    Organization_Hierarchy,
    Organization_Hierarchy.Parent_Organization_ID,
    { 
        Employee -> Employee.Organization_ID, 
        Applicant -> Applicant.Organization_ID 
    },
    { }, 
    { 
        Employee → Employee.NonActiveAttribute 
    },
    intFlag(Organization_Hierarchy.PersistentAttribute, 1)
)

profileAdjustmentLinkAttribute

Extends the target subject's profile to the period in which the source subject's attribute references the target subject's subject ID. Matches source and target subjects by the source subject's attribute and the target subject's subject ID.

Example: Let's say Employee's attribute Employee.Organization_ID references Organization Hierarchy's Organization_ID. In this example:

  • Employee is the source subject.
  • Organization_ID is the link attribute.
  • Organization Hierarchy is the target subject.

This rule behaves like adjustProfile, except:

  • The source subject and target subject match based on the source subject's attribute and the target's subject ID. The source subject ID is not used.
  • The target subject member's profile is adjusted to the time period of the source subject's attribute, not the source subject. For example, Organization Hierarchy's profile is adjusted to the period of Employee.Organization_ID.

Caution: The source subject and target subject must have the same time granularity. For more information, see Time granularity.

Syntax

Copy 
call profileAdjustmentLinkAttribute(
    sourceSubject,
    targetSubject,
    linkAttribute,
    keyMapper,
    useNonActiveAttribute,
    adjustToTermination
)
  • sourceSubject: The subject whose event stream is used to adjust the target subject's profile event stream. The source subject's profile is not modified by this rule.
  • targetSubject: The subject whose profiles are adjusted based on the source subject. The target subject's profile may be modified by this rule.
  • linkAttribute: The source subject attribute that references the subject ID of the target subject.
  • keyMapper (optional): Controls how the source subject key is translated to the target subject key. Optionally specify the property that represents the ID of the target subject or use keyDropAfter to transform the keys so that they match. The default is to use the same key to access both subject members, such as EmployeeID.
  • useNonActiveAttribute (optional, Boolean, default: false): If true, the rule considers the subject's non-active attribute and doesn't extend the target subject's profile beyond periods where the source subject is active.
  • adjustToTermination (optional, Boolean, default: false): If true, the rule pulls back the target subject's profile changes to match the source subject's first termination within the valid range, if available. This modifies the target subject's profile change events; it does not modify termination.

Let's say Employee data loads as of the end of the day but Organization Hierarchy data loads as of the end of the month. In this scenario, employees who report to a new organization at the beginning of the month will report to Unknown. To prevent this, profileAdjustmentLinkAttribute extends Organization Hierarchy back to the first usage in the month as referenced from Employee.Organization_ID.

Copy
Extends Organization_Hierarchy back to the period of Employee.Organization_ID.
call profileAdjustmentLinkAttribute(
    Employee,
    Organization_Hierarchy,
    Employee.Organization_ID
)

referenceDVPRule

Checks the validity of references between subjects, including the referenced member's parent's validity. If a source subject references an attribute in the target subject, the referenced member and its parent must be valid for the time period that the source subject references it. If the attribute isn't valid, referenceDVPRule reassigns the attribute to its default value provider (DVP). This is useful if a manager record disappears and you want the missing manager's employees to report up to the next level.

Tip: To check the validity of a member but not its parent, see referenceRule.

Syntax

Copy 
referenceDVPRule(
    sourceSubject, 
    referenceInSource, 
    targetSubject, 
    parentProvider, 
    [
        {excludedIDs}, 
        nonActiveProperty
    ]
)
  • sourceSubject : The subject that references another subject's property.
  • referenceInSource: The source subject property that is associated with the target subject.
  • targetSubject: The subject that the reference property is associated with.
  • parentProvider: The parent of the referenced property.
    • nextValidParent(): The next valid parent's ID.
  • excludedIDs (optional): The member IDs to exclude from the rule.
  • nonActiveProperty (optional): The target subject's property that indicates whether or not the member is active. If not specified, the rule checks all active and nonactive members.

Let's say you want the rule to check that all Employee subject member references to Employee.Organization_ID are valid except for Employee-1 and Employee-2. This rule checks that all referenced Organization_IDs are valid at the time of the reference, except any references from Employee-1 and Employee-2. If the Organization_IDs aren't valid, the rules reassigns Employee.Organization_ID to its next valid parent's ID.

Copy
Checks that all Employee.Organization_ID members except references from Employee-1 and Employee-2 are valid for the time periods that Employee members reference them. If invalid, reassign Employee.Organization_ID to its next valid parent's ID.
call referenceDVPRule(
    Employee, 
    Employee.Organization_ID, 
    Organization_Hierarchy, 
    nextValidParent(), 
    {"Employee-1", "Employee-2"}
)

referenceRule

Checks the validity of references between subjects. If a source subject references an attribute in the target subject, the referenced member must be valid for the time period that the source subject references it. If the attribute isn't valid, referenceRule reassigns the attribute to its default value. This is useful to remove a profile whenever it has an invalid reference.

Tip: To check the validity of a member and its parent, see referenceDVPRule.

Syntax

Copy 
referenceRule(
    sourceSubject, 
    referenceInSource, 
    targetSubject, 
    {excludedIDs}, 
    defaultValue, 
    nonActiveProperty
)
  • sourceSubject : The subject that references another subject's property.
  • referenceInSource: The source subject property that is associated with the target subject.
  • targetSubject: The subject that the reference property is associated with.
  • excludedIDs (optional): The member IDs to exclude from the rule.
  • defaultValue (optional): The value to reassign to a reference property if it is not valid.
  • nonActiveProperty (optional): The target subject's property that indicates whether or not the member is active. If not specified, the rule checks all active and nonactive members.

Let's say your Employee subject members reference Employee.Organization_ID, which is an attribute of Organization_Hierarchy. This rule checks that all referenced Organization_IDs are valid at the time of the reference. If they aren't valid, the rules reassigns Employee.Organization_ID to its default value.

Copy
Checks that all Employee.Organization_ID members are valid for the time periods that Employee members reference them.
call referenceRule(
    Employee, 
    Employee.Organization_ID, 
    Organization_Hierarchy
)

In another scenario, let's say you want the rule to check that all Employee subject member references to Employee.Organization_ID are valid except for Employee-1 and Employee-2. This rule checks that all referenced Organization_IDs are valid at the time of the reference, except any references from Employee-1 and Employee-2. If the Organization_IDsaren't valid, the rules reassigns Employee.Organization_ID to its default value.

Copy
Checks that all Employee.Organization_ID members except references from Employee-1 and Employee-2 are valid for the time periods that Employee members reference them.
call referenceRule(
    Employee, 
    Employee.Organization_ID, 
    Organization_Hierarchy, 
    {"Employee-1", "Employee-2"}
)

resolvePropertyValidityPeriod

Handles properties with a specific validity period or expiration, such as performance rating. Adjusts properties so that they start and expire as intended and fills any gaps with a default non-applicable value.

If there are validity periods with overlapping ranges, this rule converts the ranges so that they don't overlap. For example, if you have two validity periods of January to June and February to December, they overlap from February to June. The rule converts the ranges to January to February and February to December.

Caution: Different calls to resolvePropertyValidityPeriod cannot use the same startDate, endDate, and nextUpdateDate properties; unique calls must use different date properties.

To resolve the validity of multiple properties, specify all properties in the property parameter; for example:

Copy
Resolves Employee.Performance, Employee.RatingName, and Employee.SomeIntAttribute.
call resolvePropertyValidityPeriod(
    Employee,
    {
        Employee.Performance, 
        Employee.RatingName, 
        Employee.SomeIntAttribute
    },
    Employee.PerformanceStartDate,
    Employee.PerformanceEndDate,
    Employee.PerformanceNextEvalDate,
    defaultCTResolutionStrategy(Employee.Performance)
)

Syntax

Copy 
resolvePropertyValidityPeriod(
    subject, 
    property, 
    startDate, 
    endDate, 
    nextUpdate, 
    ctResolution
)
  • subject: The subject that contains the value to resolve.
  • property: One or more properties whose validity periods to resolve.
  • startDate: The earliest date from which the current property value is valid, excluding profiles that are inactive or haven't started at this date.
  • endDate: The latest date up to which the current property value is valid if another value follows, excluding profiles that were terminated or became inactive prior to this date. This end date is exclusive.

    Tip: If Performance Rating ends on 2018-01-31, its value resets to -1 on 2018-01-31 if there are future performance ratings because the end date is exclusive. To end Performance Rating on the correct date, update your Performance Rating extraction rule to the end date plus 1. In this example, the end date in the extraction rule must be 2018-02-01 to end Performance Rating on 2018-01-31.

  • nextUpdate: The next date on which an update to the property value is expected or the latest date up to which the current property value is valid if no other values follow.

  • ctResolution: A conception and termination resolution strategy. Must be one of:
    • defaultCTResolutionStrategy: Property values are valid from the start date to the end date or next update date. The value doesn't reset a day after termination because system events will handle it. The platform expects a new property value from your source files when a new profile begins.
    • extendToDayAfterTermination: Extends the last property value past the next update date up to termination.
    • keepValuePastTermination: Persists the last property value from before the last termination to when a new profile begins.
    • resetToValueOnConception: Resets the property value to a defined value on conception. The defined value is different from the default undefined value.
    • resetToValueOnConception(propertyToResetValueMap, -1): Resets multiple property values to a defined value on conception. The defined value is different from the default undefined value. The propertyToResetValueMap specifies the default value for any property in the resolvePropertyValidityPeriod.

      The property to reset value map format is:

      Copy
      { 
          property -> resetValue,
          property -> resetValue,
          ...
      }

Let's say you want to resolve the Employee.Performance property so that performance ratings are valid between the performance state date and performance end date or the next performance evaluation date.

Copy
Resolves Employee.Performance.
call resolvePropertyValidityPeriod(
    Employee,
    Employee.Performance,
    Employee.PerformanceStartDate,
    Employee.PerformanceEndDate,
    Employee.PerformanceNextEvalDate,
    defaultCTResolutionStrategy(Employee.Performance)
)

In another scenario, let's say you want to resolve the Employee.Performance, Employee.RatingName, and Employee.SomeIntAttribute properties so that performance ratings are valid between the performance state date and performance end date or the next performance evaluation date. In this example, you do not need to repeat the property names in defaultCTResolutionStrategy; instead, specify the first property.

Copy
Resolves Employee.Performance, Employee.RatingName, and Employee.SomeIntAttribute.
call resolvePropertyValidityPeriod(
    Employee,
    {
        Employee.Performance, 
        Employee.RatingName, 
        Employee.SomeIntAttribute
    },
    Employee.PerformanceStartDate,
    Employee.PerformanceEndDate,
    Employee.PerformanceNextEvalDate,
    defaultCTResolutionStrategy(Employee.Performance)
)

In another scenario, let's say you want to resolve Employee.Performance where Employee.Performance resets to a defined value on conception. In this example, the defined value is -1.

Copy
Uses resetToValueOnConception to resolve Employee.Performance to -1 on conception.
call resolvePropertyValidityPeriod(
    Employee, 
    Employee.Performance,
    Employee.PerformanceStartDate,
    Employee.PerformanceEndDate,
    Employee.PerformanceNextEvalDate,
    resetToValueOnConception(Employee.Performance, -1)
)

In another scenario, let's say you want to use resetToValueOnConception to resolve Employee.Performance, Employee.RatingName, and Employee.SomeIntAttribute to a defined value on conception. In this example, the defined value is -1.

Copy
Uses resetToValueOnConception to resolve Employee.Performance, Employee.RatingName, and Employee.SomeIntAttribute.
call resolvePropertyValidityPeriod(
    Employee, 
    {
        Employee.Performance, 
        Employee.RatingName, 
        Employee.SomeIntAttribute
    }, 
    Employee.PerformanceStartDate,
    Employee.PerformanceEndDate,
    Employee.PerformanceNextEvalDate,
    resetToValueOnConception(
        {
            Employee.Performance -> 0,
            Employee.RatingName -> "text",
            Employee.SomeIntAttribute -> 123
        }, -1
    )
)

stateReconciliationRule

Reconciles the target subject's state based on a reference subject's state. For example, if a Requisition is closed, all Applicants should also be closed.

Tip: If the reference subject is terminated but its state should still be reconciled, see extendedStateReconciliationRule instead.

Syntax

Copy 
call stateReconciliationRule(
    keyProperty,
    referenceProperty,
    targetProperty,
    referenceSubject,
    targetSubject,
    stateMap,
    gracePeriod
)
  • keyProperty: The target subject's property that references the reference subject member's ID.

    For example, if Applicant is the target subject and Requisition is the reference subject, then Applicant.RequisitionID is the key property because it references Requisition's subject member ID.

  • referenceProperty: The reference subject's property that determines the state against which to validate the target subject's state. The reference property is not modified by this rule.

    For example, if Applicant is the target subject, and Requisition is the reference subject, then Requisition.Requisition_Status is the reference property because its value is the state you want to reconcile against.

  • targetProperty: The target subject's property that determines the state to validate against the reference property's state. The target property value may be modified by this rule.

    For example, if Applicant is the target subject, Requisition is the reference subject, and Requisition.Requisition_Status is the reference property, then Applicant.Applicant_Status is the target property because its value is the state you want to reconcile.

  • referenceSubject: The subject to use to reconcile the target subject's state. The reference subject is not modified by this rule.
  • targetSubject: The subject whose state you want to reconcile. This subject's event stream may be modified by this rule.
  • stateMap (optional): The reference property values against which to validate the target subject and the specifications for how to reconcile the target subject's states. Also specifies the values to change invalid target property values to. In stateMap, only map the values that require validation.

    The state map format is:

    Copy
    {
        "referenceProperty value" -> { { "targetProperty value valid for this referenceProperty value", "another valid targetProperty value" } -> "targetProperty value to use if existing value is not valid" }
    }
  • gracePeriod (optional, default: 0): The period that the target subject's state can be invalid without being corrected by the rule with respect to the reference subject's state changes. During the grace period, the target subject's state is frozen and is unchanged by the rule. After the grace period, the target subject is reconciled to a valid state if the target subject is not valid. The grace period:
    • Is granular to 1 day.
    • Is inclusive.
    • Starts at each change of the reference subject's state, not the target subject's state.

Let's say you want to reconcile the states between Requisition and Applicant. When a Requisition is closed (Filled or Canceled), the associated Applicants must also be in a closed state (Rejected, Abandoned, or Hired Yet to Start). If the Applicant is not in one of the specified states, the rule changes the Applicant status to rejected (System Rejected), as specified in stateMap. In this example, the reference subject is Requisition and the target subject is Applicant.

This example does not specify a grace period, so it uses the default of 0 days.

Copy
Reconciles Applicant's state to Requisition's state with no grace period.
call stateReconciliationRule(
    Applicant.RequisitionID,
    Requisition.Requisition_Status,
    Applicant.Applicant_Status,
    Requisition,
    Applicant,
    {  
        "Filled" -> { { "Rejected", "Abandoned", "Hired Yet to Start" } -> "System Rejected" },
        "Canceled" -> { { "Rejected", "Abandoned" } -> "System Rejected" }
    }
)

In a similar scenario, let's say that the reference subject, Requsition, has a state change on January 1st at 13:55 to Filled. In this example, a grace period of 3 days extends up to and including January 4th at 13:55. Any state changes to target subject, Applicant, between January 1st at 13:55 and January 4th at 13:55 are frozen and unchanged by the rule. This means that within the 3 day grace period, Applicant's state can change without any impact by the rule. To be valid at the end of the grace period, Applicant's state must be Rejected, Abandoned, or Hired Yet to Start, as specified in stateMap. If it isn't, the state is invalid and the rule changes the state to System Rejected on January 4th at 13:55.

Copy
Reconciles Applicant's state to Requisition's state with a 3 day grace period.
call stateReconciliationRule(
    Applicant.RequisitionID,
    Requisition.Requisition_Status,
    Applicant.Applicant_Status,
    Requisition,
    Applicant,
    {  
        "Filled" -> { { "Rejected", "Abandoned", "Hired Yet to Start" } -> "System Rejected" },
        "Canceled" -> { { "Rejected", "Abandoned" } -> "System Rejected" }
    },
    3
)

Arguments

You can use the following arguments in your multi-subject rule formulas.

date

The format is date(yyyy, MM, dd). Used in:

defaultCTResolutionStrategy

Property values are valid from the start date to the end date or next update date. The value doesn't reset a day after termination because system events will handle it. The platform expects a new property value from your source files when a new profile begins. Used in:

extendToDayAfterTermination

Extends the last property value past the next update date up to termination. Used in: 

intFlag

Indicates whether the hierarchy member can be pruned. Default is to allow pruning of any hierarchy member. Used in:

keepValuePastTermination

Persists the last property value from before the last termination to when a new profile begins. Used in:

keyDropAfter

  • Transforms the source subject key and target subject key so that they match. Used in: 

nextValidParent

The next valid parent's ID. Used in:

resetToValueOnConception

Resets the property value to a defined value on conception. The defined value is different from the default undefined value. Used in: