About ID Match Integration

Registry v3.3.0 and later support integration with an ID Match server that implements the SOR-Registry Strawman ID Match API, such as COmanage Match. Support is currently available for Organizational Identity Sources (OIS) connected to Pipelines, and as of Registry v4.0.0 for use with Enrollment Flows.

Registry supports two models for ID Match Integration:

  • Match Before Registry: ID Match is called before SOR data is initially presented to Registry, such that the SOR data already includes the Reference Identifier.
  • Match At Registry: ID Match is called by Registry upon receipt of a new SOR record. The SOR data does not include the Reference Identifier.

Match Before Registry

If the Reference Identifier will already be included in the OIS record, use the Identifier Pipeline Match Strategy. Records with the same Identifier of the specified type will automatically be linked together.

When Match Before Registry is used, the Match Reference Identifier will be available in the Org Identities associated with each backend, as well as the CO Person Record.

Match At Registry

The remainder of this document describes Match At Registry.

When Match At Registry is used with Organizational Identity Sources, the Match Reference Identifier will be available in the Org Identity Source Record (Org Identity > View Organizational Identity Source Record), but not in the Org Identity itself. It will also be available in the CO Person Record. When Match At Registry is used with Enrollment Flows, the Match Reference Identifier will be available in the Petition record and the CO Person Record.

System of Record Labels

The Match API operates with the concept of a System of Record Label, which is used to identify the calling system making the request to the ID Match server. System of Record Labels should be short and alphanumeric with no special characters, such as sis or hris.

System of Record Labels (v4.1.0 and later)

In Registry v4.1.0 and later, the System of Record labels are defined in the Organizational Identity Source or Enrollment Flow configuration. A unique System of Record label should be used for each configuration.

System of Record Labels (v4.0.x)

Registry supports two models for SOR Labels:

  1. Single SOR: A single SOR Label is defined (eg: registry) and used for all Match requests. This model is simpler to set up, but only works if SOR IDs are unique across all OIS backends (and not just within the backend asserting a particular record) and, if Enrollment Flow matching is used, Registry's internal CO Person IDs (which are integers). For example, if the Student System and HR System might assign the same SOR ID, this model cannot be used.
  2. SOR per Source: A SOR Label is defined for each OIS backend (eg: sis, hris), and for each or all Enrollment Flows. (Registry will assign unique internal IDs across the entire platform, so it is safe to use the same SOR Label for multiple Enrollment Flows.) This model requires more configuration, but provides for better data isolation.

(warning) When using COmanage Match, it is not possible to use the same SOR Label for both Pipelines and Enrollment Flows, since Pipelines require External resolution and Enrollment Flow require Interactive resolution.

Match Servers

To define a Match Server, go to Registry > Servers > (plus) Add a New Server. Set the server type to Match.

On the configuration page, set the appropriate values to connect to the Match Server:

  • Server URL: The URL prefix for Match request. This should look something like https://match.university.edu/match/api/3/v1.
  • Username and Password: As configured.
  • SOR Label: As defined on the Match server, and in accordance with the model selected above. If the SOR per Source model is chosen, then a Match Server will need to be defined for each SOR Label. (Registry v4.0.x only)

Match Attributes

After the Match Server is defined, Match Server Attributes can be added to the configuration to define which attributes Registry will send when making a match request. This configuration should align with the Match Server's attribute configuration.

  • For Pipelines, Match Attributes are pulled from the Org Identity, since the point of the Match operation is to determine which CO Person record to connect the Org Identity to.
  • For Enrollment Flows, Match Attributes are pulled from the CO Person, since the attributes collected during an Enrollment Flow are intended to primarily represent a CO Person identity.

The following attributes are supported:

  • Date of Birth, which must be YYYY-MM-DD format
  • Email Address
  • Identifier
  • Name

Attributes other than Date of Birth may be specified multiple times using different types. For example, a National ID number and an ID Card number can be configured by adding two Identifiers, one of type national and the other of type badge.

Attributes configured as Required must be present in the source identity. If any Required attribute is not found, the Match request will not be submitted. The record must be corrected before trying again.

Match Server Attributes were added in Registry v4.0.0. Registry v3.3.x uses a hard coded list of attributes

SOR IDs are automatically calculated, and should not be explicitly configured. For Organizational Identity Sources, the Backend's unique ID (key) will be used as the SOR ID. For Enrollment Flows, the Registry internal CO Person ID key (an integer) will be used.

See also: COmanage Match Attributes

Enrollment Flow Configuration

Currently, Match integration is only recommended for administrator driven enrollment flows, ie those where Petitioner Enrollment Authorization is set to CO Admin or COU Admin. In particular, Match integration is not suitable for use with Self Signup flows. (CO-2317)

This is due to the possibility that a match request will generate possible matches that must be reviewed before a Reference Identifier can be assigned. The only currently process supported within Enrollment Flows for potential match resolution is interactive, and in most scenarios it is a security risk to allow a self signup user to select their own match resolution. Additionally, Email Addresses need not be verified for match requests.

  1. Configure the Enrollment Flow with Identity Matching set to External. Select the appropriate Match Server from the list provided.
  2. Make sure the Enrollment Attributes collected include CO Person attributes with the same configuration (including types, if appropriate) as the Match Server Attributes.
  3. Set Duplicate Enrollment Mode to an appropriate configuration.
  4. For Registry v4.1.0 and later, define the System of Record Label.

Handling Fuzzy Matches

If the match request is inconclusive, a list of potential candidates will be displayed as part of the Enrollment Flow. To link to an existing record, select the appropriate Reference Identifier. To create a new Reference Identifier, select "New".

(warning) When connected to COmanage Match, the SOR should be configured with a Resolution Mode of Interactive.

Updating Match Attributes

Updating Match Attributes for Match Requests created by Enrollment Flows is not currently supported. (CO-2318)

Organizational Identity Source Configuration

  1. For Registry v4.1.0 and later, define the System of Record Label.
  2. Attach a Pipeline to the OIS with a Match Strategy of External, and select the appropriate Match Server, defined above.

Handling Fuzzy Matches

If the match request is inconclusive, the Pipeline will fail. An administrator must login to the Match server and resolve the conflict. On the next attempt to process the Pipeline, the Reference ID will be obtained and processing will complete. Alternately, if the inconclusive result was caused by bad data in the SOR record, the record can be corrected and will be successfully processed on the next execution of the Pipeline.

(warning) When connected to COmanage Match, the SOR should be configured with a Resolution Mode of External.

Updating Match Attributes

Once a Reference Identifier is assigned, if the underlying OIS record is changed (eg: if the person's name is updated in the upstream data source) no automatic rematching will take place. However, an Update Match Attributes request will be sent to the Match server, so that the Match server has the latest attributes for future matching operations.

Currently, records are never removed from the Match server, even after an expunge from Registry.

Match Resolution Notification Configuration

As of v4.1.0, Registry supports Match's Match Resolution Endpoint Notification Protocol via the Match Callback Core API.

When a Match Resolution Notification is received, Registry will attempt to map the SOR Label and SOR ID to an Organizational Identity Source using the System of Record Label configured on the OIS. If a matching configuration is found, a Sync Job will be queued to reprocess the SOR ID within the OIS, the Job will be processed the next time Job Shell processes the queue. (The record is not processed synchronously on receipt of the notification.)

To enable Match Resolution Notification processing:

  1. Create a new API User via Configuration > API Users > (plus) Add API User.
    1. The API User should not be Privileged.
    2. After creating the API User, generate an API Key.
    3. (info) An existing API User can be reused if appropriate.
  2. Enable the Core API via Configuration > Core APIs > (plus) Add Core API.
    1. Select the Match Callback API.
    2. Set the API User created in the previous step.
  3. The full callback URL is available in the Match Server configuration.

(warning) Match Resolution Notification does not currently support Match Requests generated by Enrollment Flows.


  • No labels