Creating a Universal Matching Service

A universal matching service is a service that can use any of your match rules to perform matching and can accept any input fields. The service takes a match rule name as an input option, allowing you specify the match rule you want to use in the API call or web service request. The service does not have a predefined input schema so you can include whatever fields are appropriate for the type of records you want to match. By creating a universal matching service you can avoid having separate services for each match rule, enabling you to add new match rules without having to add a service.

This procedure shows how to create a universal matching service and includes an example of a web service request to the universal matching service.

  1. In Enterprise Designer, create a new service dataflow.
  2. Drag an Input stage, a Transactional Match stage, and an Output stage to the canvas and connect them so that you have a dataflow that looks like this:
  3. Double-click the Transactional Match stage.
  4. In the Load match rule field, select any match rule. For example, you can select the default Household match rule.

    Even though you will specify the match rule in the service request, you have to configure the Transactional Match stage with a default match rule in order for the dataflow to be valid. If you do not select a match rule the dataflow will fail validation and you will not be able to expose it.

  5. Click OK.
  6. Double-click the Output stage.
  7. Choose to expose the fields MatchRecordType and MatchScore.
  8. Click OK.
    Note: There is no need to expose any fields in the Input stage since input fields will be specified as user-defined fields in the service request.
  9. Click Edit > Dataflow Options.
  10. Click Add.
  11. Expand Transactional Match and check the box next to Match Rule.

    This exposes the match rule option as a run-time option, making it possible to specify the match rule in the service request.

  12. Click OK then click OK again to close the Dataflow Options window.
  13. Save and expose the dataflow.

You now have a universal match service that you can use to perform matching using any of the match rules defined in the Match Rules Management tool in Enterprise Designer. When calling the service, specify the match rule in the MatchRule option and specify the input fields as user-defined fields.

Example: Calling the Universal Matching Service

You have created a match rule named AddressAndBirthday in the Match Rules Management tool. This match rule matches records using the fields Address and Birthday. You want to use the universal matching service to perform matching using this rule through a SOAP web service request.

To accomplish this, you would have a SOAP request that specifies AddressAndBirthday in the MatchRule element and the record's fields in the user_fields element.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:univ="http://www.pb.com/spectrum/services/UniversalMatchingService">
   <soapenv:Header/>
   <soapenv:Body>
      <univ:UniversalMatchingServiceRequest>
         <univ:options>
            <univ:MatchRule>AddressAndBirthday</univ:MatchRule>
         </univ:options>
         <univ:Input>
            <univ:Row>
               <univ:user_fields>
                  <univ:user_field>
                     <univ:name>Name</univ:name>
                     <univ:value>Bob Smith</univ:value>
                  </univ:user_field>
                  <univ:user_field>
                     <univ:name>Address</univ:name>
                     <univ:value>4200 Parliament Pl</univ:value>
                  </univ:user_field>
                  <univ:user_field>
                     <univ:name>Birthday</univ:name>
                     <univ:value>1973-6-15</univ:value>
                  </univ:user_field>
               </univ:user_fields>
            </univ:Row>
            <univ:Row>
               <univ:user_fields>
                  <univ:user_field>
                     <univ:name>Name</univ:name>
                     <univ:value>Robert M. Smith</univ:value>
                  </univ:user_field>
                  <univ:user_field>
                     <univ:name>Address</univ:name>
                     <univ:value>4200 Parliament Pl</univ:value>
                  </univ:user_field>
                  <univ:user_field>
                     <univ:name>Birthday</univ:name>
                     <univ:value>1973-6-15</univ:value>
                  </univ:user_field>
               </univ:user_fields>
            </univ:Row>
            <univ:Row>
               <univ:user_fields>
                  <univ:user_field>
                     <univ:name>Name</univ:name>
                     <univ:value>Bob Smith</univ:value>
                  </univ:user_field>
                  <univ:user_field>
                     <univ:name>Address</univ:name>
                     <univ:value>424 Washington Blvd</univ:value>
                  </univ:user_field>
                  <univ:user_field>
                     <univ:name>Birthday</univ:name>
                     <univ:value>1959-2-19</univ:value>
                  </univ:user_field>
               </univ:user_fields>
            </univ:Row>
         </univ:Input>
      </univ:UniversalMatchingServiceRequest>
   </soapenv:Body>
</soapenv:Envelope>

This request would result in the following response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns3:UniversalMatchingServiceResponse xmlns:ns2="http://spectrum.pb.com/"
      xmlns:ns3="http://www.pb.com/spectrum/services/UniversalMatchingService">
         <ns3:Output>
            <ns3:Row>
               <ns3:MatchScore/>
               <ns3:MatchRecordType>Suspect</ns3:MatchRecordType>
               <ns3:user_fields>
                  <ns3:user_field>
                     <ns3:name>Name</ns3:name>
                     <ns3:value>Bob Smith</ns3:value>
                  </ns3:user_field>
                  <ns3:user_field>
                     <ns3:name>Birthday</ns3:name>
                     <ns3:value>1973-6-15</ns3:value>
                  </ns3:user_field>
                  <ns3:user_field>
                     <ns3:name>Address</ns3:name>
                     <ns3:value>4200 Parliament Pl</ns3:value>
                  </ns3:user_field>
               </ns3:user_fields>
            </ns3:Row>
            <ns3:Row>
               <ns3:MatchScore>100</ns3:MatchScore>
               <ns3:MatchRecordType>Duplicate</ns3:MatchRecordType>
               <ns3:user_fields>
                  <ns3:user_field>
                     <ns3:name>Name</ns3:name>
                     <ns3:value>Robert M. Smith</ns3:value>
                  </ns3:user_field>
                  <ns3:user_field>
                     <ns3:name>Birthday</ns3:name>
                     <ns3:value>1973-6-15</ns3:value>
                  </ns3:user_field>
                  <ns3:user_field>
                     <ns3:name>Address</ns3:name>
                     <ns3:value>4200 Parliament Pl</ns3:value>
                  </ns3:user_field>
               </ns3:user_fields>
            </ns3:Row>
         </ns3:Output>
      </ns3:UniversalMatchingServiceResponse>
   </soap:Body>
</soap:Envelope>