searchNotifications

  • Web Services
  • UMPI
  • API Documentation

The searchNotifications web service is used to retrieve notification messages from Universal MPI within a specified time range. Notification messages are continually queued in Universal MPI, and you can choose how frequently they want to use the searchNotifications web service to retrieve notifications.

  • Notification messages are generated for several different types of events. 
  • Notification messages are not deleted. You can retrieve the same notification messages again by calling the searchNotifications web service again with the same time range.

Pagination

The searchNotifications web service response uses pagination so you can control the amount of information retrieved in each web service response.

The request includes an input for pageSize, which can be any integer between 1 and 100. The request also includes an input for pageNumber, which can be any integer equal to or greater than 0. The pageNumber is a zero-based index, so the first page is pageNumber=0, the second page is pageNumber=1, and so on.

Tip
Pagination can help your manage notifications. For example, if the searchNotifications web service is called frequently (for example, every 30 minutes), each individual web service response would typically include a small number of notifications. However, if searchNotifications service is called infrequently (once per week, for example), then he number of notifications could grow very large.

searchNotifications JSON request

  • The request includes:

    • A tracking ID (an optional identifier that the client can supply to track the response)
    • The startDate and endDate, inclusive, that define the time range for which to retrieve notifications. The startDate and endDate format is ISO datetime format: YYYY-MM-DDThh:mm:ss. The default time zone is UTC, but the time zone can be adjusted with a modifier at the end of the datetime. The modifier is in the form of +/-hh:mm.
      For example, a request with startDate=2019-12- 06T13:44:21-05:00 is indicating that the start date is 5 hours behind UTC (5 hours behind UTC is US Eastern time zone). The searchNotifications request will fail if the start date is greater than the end date.
    • The pageSize to use for pagination. Page size value must be an integer greater than 0 and less than or equal to 100, otherwise the searchNotifications request will fail.
    • The pageNumber to use for pagination. The pageNumber is a zero-based index, so pageNumber=0 indicates the request is for the first page of notifications. The web service response indicates if there are subsequent pages, in which case you can make a subsequent searchNotifications request with pageNumber=1, and so on.
  • {
      "content": { 
        "pageNumber": integer,
        "endDate": "YYYY-MM-DDThh:mm:ss", 
        "pageSize": integer,
        "startDate": "YYYY-MM-DDThh:mm:ss"
      },
      "trackingId": "string"
    }
    

searchNotifications JSON response

  • The response includes:

    • An ‘echo’ of the same tracking ID from the request
    • Several Boolean and string values with more information about the success/failure of the service (see section 3.1 above for more information)
    • The ‘customerId’ identifier for the Universal MPI instance from which the notifications were retrieved. Clients typically have a production Universal MPI instance and one or more non- production Universal MPI instances. The ‘customerId’ is useful to confirm that you retrieved notifications from the Universal MPI instance you intended.
    • A ‘hasNext’ Boolean value to indicate whether there is a subsequent page of notification messages. When ‘hasNext’ is false, there are no additional pages of notification messages to retrieve; when ‘hasNext’ is true, there are still additional pages of notification messages to retrieve, and you should invoke searchNotifications again to retrieve the additional pages (with an incremented pageNumber).
    • A ‘totalElements’ integer which is the count of total notification messages that exist for the time range specified in the request. The ‘totalElements’ count can be higher than the ‘pageSize’ input parameter, which indicates that the notification messages will be distributed across multiple pages/responses.
    • An array of zero-to-many notification messages.
  • {
       "trackingId": "string", 
       "auditId": UUID, 
       "success": boolean, 
       "retryableError": boolean, 
       "message": "string", 
       "errors": [
         "string"
       ],
       "content": {
         "hasNext": boolean,
         "totalElements": integer, 
         "customerId": "string", 
         "notifications": [
    { "ts": integer, "service": "string", "body": "string" } ] } }

Notification array entries

Each entry in the notification array includes three pieces of information

  • TS – The timestamp of the notification message in Unix ‘epoch’ format (the number of milliseconds since 12AM, Jan. 1, 1970). For example, the “ts” value of 1574462976506 equates to Friday, November 22, 2019 10:49:36.506 PM
  • Service – The internal Universal MPI service that generated the notification message. See below for the possible values of service.
  • Body – the body that contains the details of the notification message – the contents of the body will vary depending on the type of notification message. The contents of the body are JSON-within-JSON – because the contents of the “body” are part of a JSON web service response, any instances of the double-quote character within the “body” are escaped with the \ character.

Possible values and indications for service are as follows:

  • ingestionService – The overlay rejection, initial Link ID assignment, or LinkID change occurred during the ingestion of a postIdentity web service
  • linkIdentitiesService – The LinkID change occurred because the linkIdentities web service was invoked. The linkIdentities web service can be called directly, but it is also used by the Universal MPI User Interface (UI) when a user manually links identities through the UI.
  • unlinkIdentitiesService – The LinkID change occurred because the unlinkIdentities web service was invoked. The unlinkIdentities web service can be called directly, but it is also used by the UI when a user manually unlinks records through the UI.
  • mergeIdentitiesService – The LinkID change occurred because the mergeIdentities web service was invoked
  • unmergeIdentitiesService – The LinkID change occurred because the unmergeIdentities web service was invoked
  • deleteSourceService – The LinkID change occurred because the deleteSourceIdentity web service was invoked

Service / Body values table

The following table describes the various scenarios and possible “service” and “body” values you can expect to find in the notification messages.

Scenario Service Body

A postIdentity request is rejected because an overlay was detected. The existing attribute values for JOHN SMITH were completely updated to different values for RONALD BRAT, but the update was rejected because the updated attributes scored only 0.09 when compared to the existing values.

Note that the “body” of the notification message includes the Source + Native ID of the postedIdentity, the incoming attribute values, the existing attribute values, and the score of the match comparison between incoming and existing values.

Ingestion Service "{\"score\":0.09647058823529411,\"source\ ":\"test\",\"nativeID\":\"0001\",\"incoming\":{\"nativeId\":\"0001\",\"source\":\" test\",\"personName\":[{\"first\":\"RONALD\",\"last\":\"BRAT\"}],\"credentials\":[ {\"ssn\":\"991110011\"}],\"birthDetails\" :[{\"date\":\"1975-11- 02\"}],\"deathDetails\":[],\"physicalDescription\":[{}],\"detailedAddress\":{\"houseNumber\":\"521\",\"streetName\":\"BOARD\",\"streetType\":\"ST\",\"city\":\"REST  ON\",\"state\":\"VA\",\"zipCode\":\"22100 \"}],\"simpleAddress\":[],\"contactPhone\ ":[{}],\"contactEmail\":[{}],\"employment \":[],\"ipData\":[],\"socialNetworkingId\ ":[]}, \"existing\":{\"nativeId\":\"0001\",\"source\":\"test\",\"personName\":[{\"first\" :\"JOHN\",\"last\":\"SMITH\"}],\"credenti als\":[{\"ssn\":\"999112222\"}],\"birthDe tails\":[{\"date\":\"1980-12- 04\"}],\"deathDetails\":[],\"physicalDescription\":[],\"detailedAddress\":[{\"houseNumber\":\"123\",\"streetName\":\"MAIN\" ,\"streetType\":\"ST\",\"city\":\"MCLEAN\ ",\"state\":\"VA\",\"zipCode\":\"22102\"} ],\"simpleAddress\":[],\"contactPhone\":[ ],\"contactEmail\":[],\"employment\":[],\ "ipData\":[],\"socialNetworkingId\":[]}}"
Native id 0006, from source ‘test’, was posted for the first time and received an initial Link ID assignment. Ingestion Service "{\"source\":\"test\",\"nativeId\":\"0006\",\"newLinkId\":\"5cf196cf59f4fc25a684c3 e1\"}"
Native id 0006, from source ‘test’, has a change in assigned Link ID due to a postIdentity update – the postIdentity update included new attribute values that allowed Universal MPI to recognize a better match, resulting in a new Link ID assignment. Ingestion Service "{\"source\":\"test\",\"nativeId\":\"0006\",\"previousLinkId\":\"5cf196cf59f4fc25a684c3e1\",\"newLinkId\":\"5cf198fc59f4fc2 5a684c3e2\"}"
The linkIdentities web service was invoked to link native ID 0002, from source ‘test’, into a different Link ID. linkIdentitiesService "{\"source\":\"test\",\"nativeId\":\"0002\",\"previousLinkId\":\"5cf14a2d59f4fc25a684c3dc\",\"newLinkId\":\"5cf1484a59f4fc2 5a684c3db\"}"
The unlinkIdentities web service was invoked to unlink native ID 0002, from source ‘test’, out of its current Link ID into a brand new Link ID. unlinkIdentitiesService "{\"source\":\"test\",\"nativeId\":\"0002\",\"previousLinkId\":\"5cf1484a59f4fc25a684c3db\",\"newLinkId\":\"5cf1509459f4fc2 5a684c3df\"}"
The mergeIdentities web service was invoked to merge native ID 1003, from source ‘test’, into a different Link ID (native ID 1004). mergeIdentitiesService "{\"source\":\"test\",\"nativeId\":\"1003\",\"previousLinkId\":\"5dc1ed4eded58f000ec9322a\",\"newLinkId\":\"5dc1ed4dded58f0 00ec93229\",\"survivingSource\":\"test\",\"survivingNativeId\":\"1004\",\"retiredSource\":\"test\",\"retiredNativeId\":\"1003\"}"
The unmergeIdentities web service was invoked to unmerge native ID 1003, from source ‘test’, out of its current Link ID into a brand new Link ID. unmergeIdentitiesService "{\"source\":\"test\",\"nativeId\":\"1003\",\"previousLinkId\":\"5dc1ed4dded58f000ec93229\",\"newLinkId\":\"5dc1ed4fded58f0 00ec9322b\"}"
The deleteSourceIdentity web service was invoked to delete native ID 0003 from source ‘test’. Note that in this case, the “newLinkId” is reported as the same value as “previousLinkId” – the Link ID did not truly change, rather the source record was deleted out of Universal MPI (while other source records still exist in that Link ID). deleteSourceService ”{\”source\”:\”test\”,\”nativeId\”:\”0003\”,\”previousLinkId\”:\”5cf14aef59f4fc25a 684c3dd\”,\”newLinkId\”:\”5cf14aef59f4fc2 5a684c3dd\”}”
The deleteSourceIdentity web service was invoked to delete native ID 0009 from source ‘test’, when test:0009 is the very last record associated with the Link Id. deleteSourceService ”{\”source\”:\”test\”,\”nativeId\”:\”0009\”,\”previousLinkId\”:\”5cf14aef59f4fc25a 684c3dd\”,\”newLinkId\”:\”5cf14aef59f4fc2 5a684c3dd\”}”

searchNotifications example 1

  • This example shows how the searchNotifications web service behaves with pagination.

    With this request, the client is asking for all notification messages generated between 17:00 and 18:00 (inclusive) on November 21, 2019. In addition, the client is requesting the first page of notification messages (pageNumber=0) with a page size of 2 messages. Suppose that 3 notification messages exist in Universal MPI for that time range. Suppose that that a client sends the following request to the searchNotifications web service:

    {
      "content": { 
        "pageNumber": 0,
        "pageSize": 2,
        "startDate": "2019-11-21T17:00:00", 
        "endDate": "2019-11-21T18:00:00"
      },
    "trackingId": "Test20191125"
    }
    
  • The hasNext Boolean indicates there is at least one more page of notifications remaining.

    The totalElements integer indicates there are three total notification messages for this time period. If the client submitted a second searchNotifications request to retrieve the next page, they should expect to receive one additional notification message.

    {
      "success":true,
      "content": {
        "hasNext":true,
        "totalElements":3,
        "notifications": [
          { 
            "ts":1574462976506,
            "service": "ingestionService",
            "body": "{\"source\":\"test\",\"nativeId\":\"13843\",\"previousLinkId\":
    \"5dd865ed8b0f0e14c5487dfb\",\"newLinkId\":\"5dd865ef8b0f0e14c5487e0d\"}"
          },
          {
            "ts":1574462976792,
            "service":"ingestionService",
            "body":"{\"source\":\"test\",\"nativeId\":\"13839\",\"previousLinkId\":
    \"5dd865f48b0f0e14c5487e20\",\"newLinkId\":\"5dd865f78b0f0e14c5487e2a\"}"
          }
        ],
        "customerId":"cust9999-test"
        },
          "trackingId":"Test20191125",
          "auditId":"43f08c66-bfab-4eca-b51a-e24701d5140e", 
          "retryableError":false
    }
    

searchNotifications example 2

  • To retrieve the next page, the client increments the pageNumber and submits this request:

    {
      "content": { 
        "pageNumber": 1,
        "pageSize": 2,
        "startDate": "2019-11-21T17:00:00", 
        "endDate": "2019-11-21T18:00:00"
      },
    "trackingId": "Test20191125"
    }
    
  • The ‘hasNext’ Boolean indicates there are no additional pages, and as expected, there is only one notification message for this page number, because the first 2 messages were retrieved in the previous page.

    
    {
      "success":true,
      "content":
        {
          "hasNext":false,
          "totalElements":3,
          "notifications": [
            {
              "ts":1574462976987,
              "service":"ingestionService",     
              "body":"{\"source\":\"test\",\"nativeId\":\"13832\",\"previousLinkId\":
    \"5dd865f28b0f0e14c5487e10\",\"newLinkId\":\"5dd865f78b0f0e14c5487e2a\"
            }"
        }
        ],
          "customerId":"cust9999-test"
        },
          "trackingId":"Test20191125",
          "auditId":"1dfcdf25-065c-4d3b-9616-22784ccc457c", 
          "retryableError":false
    }