How do I configure an advanced reconciliation definition?

You can create a reconciliation (rec) definition to tell LUSID what data to compare and how to compare it. The definition specifies:

• The portfolios on each side

• The types of reconciliation to perform

• The matching rulesets to apply

• How the results are reviewed and approved

Recommended reading: Understanding advanced reconciliations, How do I create a matching ruleset?

Prerequisites

Before getting started, ensure you have already created:

• The portfolios, portfolio groups, or funds you want to reconcile

• A matching ruleset for each reconciliation type you want to include

• A recipe for each side of the reconciliation

Methods

curl -X POST "https://<your-domain>.lusid.com/api/api/recs/definitions"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json" 
  -d '{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "HoldingUnitsReconciliation"
  },
  "displayName": "Compare holding units",
  "description": "Compares holding units between our records and the custodian'\''s records",
  "sideNames": {
    "left": "LUSID",
    "right": "Custodian"
  },
  "details": {
    "definitionType": "PortfolioContents",
    "leftPortfolioSources": [
      {
        "sourceType": "Portfolio",
        "id": { "scope": "Finbourne-Examples", "code": "EU" }
      }
    ],
    "rightPortfolioSources": [
      {
        "sourceType": "Portfolio",
        "id": { "scope": "Finbourne-Examples", "code": "EU-Custodian" }
      }
    ],
    "rulesets": [
      {
        "recType": "Holding",
        "matchingRulesetId": { "scope": "Finbourne-Examples", "code": "HoldingUnitsRule" }
      }
    ],
    "valuationRecipes": {
      "left": { "scope": "Finbourne-Examples", "code": "EU-Equities" },
      "right": { "scope": "Finbourne-Examples", "code": "EU-Equities" }
    },
    "currencies": {
      "left": "EUR",
      "right": "EUR"
    }
  },
  "reviewConfiguration": {
    "openExceptions": { "reviewRequirement": "Required" },
    "closedExceptions": { "reviewRequirement": "NotRequired" },
    "matches": { "reviewRequirement": "NotRequired" },
    "reviewSubmission": {
      "completionRatioThreshold": 1.0,
      "autoSubmit": false
    },
    "requiredApprovals": [
      {
        "approvalCode": "Desk",
        "description": "Desk sign-off"
      }
    ]
  }
}'

Fields

Definition type

You must use the relevant type for the kind of data the rec definition compares.

Sources

The sources tell LUSID what data to compare on each side. For each side, you specify:

• A side name to label each side in your results, for example LUSID or Custodian.

• One or more portfolios, portfolio groups, or funds.

  Using relational data for one side

  Instead of portfolios, portfolio groups, or funds, one side can use relational data, for example a dataset loaded from a custodian. Only one side can use relational data.
  
  You don't choose the dataset in the reconciliation definition; you name it on each reconciliation type's matching ruleset instead. Note:

  • Each matching ruleset must fit the kind of source on each side.

  • If you change a side between portfolio data and relational data, you need to choose matching rulesets that fit the new sources.

  • When you select Relational data sources in the web app, LUSID removes all the reconciliation types you've already added for that side, so choose your sources first.

LUSID compares the same sources for each reconciliation type in the rec definition.

Rec types and matching rulesets

For each type of reconciliation you want to include in the definition, you must choose a matching ruleset that decides how LUSID compares it. Note the following:

• You can only include one of each rec type in the definition.

• A matching ruleset must match both of the following:

  • The rec type.

  • The kind of source on each side (either portfolio data or relational data).

If you can’t find a matching ruleset from the selector in the LUSID web app, check its rec type is correct.

If one side uses relational data, you can also add a relational data filter for each reconciliation type, for example custodian eq 'MyCustodian'.

Valuation recipes and currencies

For each side that uses portfolios, portfolio groups, or funds, you must specify a valuation recipe and a currency. Both are required, even if you're not reconciling valuations.

Note

Neither field is required when the side uses relational data.

Date policy

Each time you run a reconciliation definition, LUSID creates a new instance. The date policy controls how each instance's dates relate to the previous instance, and what changes when you rerun an instance.

⚠️ Warning

You cannot change the date policy once the rec definition has an instance.

Your date policy also decides two things you don't set directly:

• Rerun: Whether you can rerun an instance. You can't rerun if both sides use Explicit As at dates, because nothing would change.

• Break ageing: Whether LUSID tracks how long a break has stayed open across instances, so you can see which breaks are persistent. LUSID tracks it automatically when Effective date progression is Series and both sides use the Latest As at dates.

Effective date progression

When you create a rec instance, you set an effectiveAt date for the data you want to reconcile on each side. For example, LUSID compares the holdings each side has on that effectiveAt date.

• Series: Both effectiveAt dates must be later than the previous instance's, so your instances form a timeline.

• Unconstrained: Each instance can use any dates.

Note

This does not apply to reruns. A rerun isn't a new instance; it keeps the instance's effectiveAt dates, and you can rerun an earlier instance in a series without affecting the instances after it.

As at dates

If your Effective date progression is set to Unconstrained, you can allow users to specify an asAt date for each side when creating a new instance:

• Latest (default): LUSID always uses the latest version of the data, including any corrections. This allows you to fix data and rerun to check your fixes.

• Explicit: Set a specific asAt date when you create a new instance.

Activity window

Required for the following rec types and when Effective date progression is set to Series:

• Input transactions

• Output transactions

• Settlement activity

Currently, the only Window type option is Contiguous. This means each instance covers the activity since the previous instance’s effective date, so there are no gaps or overlaps.

Note

A rerun of an instance maintains the same window.

The following table shows you how you could configure various example use cases:

Review and approval

Results review

You can specify which types of results require review:

• Open exceptions: Breaks, partial matches, and partial crosses that aren't resolved

• Closed exceptions: Exceptions that were accepted, force matched, or cleared on a rerun

• Matches: Matches and crosses

You can add a condition for each type of result using LUSID filtering syntax to exclude certain results from your Review requirement setting.

Review submission

You can set a Minimum review completion percentage, so that:

• A reviewer can't submit a result set until enough results are reviewed.

• If enabled, LUSID automatically submits for approval once the percentage is reached.

Required approvals

If a result set needs sign-off, you can add a required approval for each one, for example Desk and Risk.

Every approval must come from a different user. You can restrict who gives each approval using approver criteria such as:

• id: The user’s ID.

• type: The user’s account type, for example Personal.

• role.scope and role.code: The scope and code of a role assigned to the user.  

For example, role.code eq 'RiskApprover' allows any user with the RiskApprover role to give the approval.

Leave the criteria blank to allow any user to give approval.

For more information on how review and approval works, see Understanding result sets in advanced reconciliations.

Updating a rec definition

Once created, you can update a rec definition via:

• LUSID web app: Find the definition in the Rec Definitions dashboard and click the Edit icon.
  

• LUSID API: Call the UpdateRecDefinition API. Note this replaces the whole definition; any omitted fields are set to null.

Note that you cannot update the following:

• The rec definition’s scope and code

• Definition type

• Date policy (unless the rec definition has never created an instance)