Add Flow

Owned by Nancy Mond
Last updated: Dec 13, 2010Version comment
5 min read

Introduction

This document describes some sample flows for adding people and their roles to the Registry and a general explanation of the process.

The following is a sample add person request from System of Record (SoR) 123:

https://test-registry.rutgers.edu/api/v1/sor/123/people

POST /api/v1/sor/123/people HTTP/1.1
Host: test-registry.rutgers.edu
Content-Type: application/xml
Authorization: Basic cmF0czpSQVQxMjM0

<?xml version="1.0"?>
<open-registry-person sor-person-id="124">
    <dob>1967-09-23</dob>
    <ssn>035551478</ssn>
    <gender>F</gender>
    <names>
       <name type="FORMAL" first="Cindy" last="Simon" />
    </names>
    <reconciliation>
	<emails>
            <email>simon@gmail</email>
        </emails>
        <phones>
            <phone>908-445-3355</phone>
        </phones>
        <address>
          <address-line1>123 Main St.</address-line1>
          <address-line2>Suite 5</address-line2>
          <city>New Brunswick</city>
          <region>NJ</region>
          <postal-code>08819</postal-code>
        </address>
   </reconciliation>
</open-registry-person>

The following shows an example response when the person is successfully added to the Registry.

Sample Response:

HTTP/1.x 201 Created
Location: [https://test-registry.rutgers.edu/api/v1/people/NETID/JC01]
Content-Type: application/x-www-form-urlencoded

activationKey=Er5ZcDem

A return code of 201 indicates that the person was successfully added to the Registry. The preferred identifier, in this case NetID, is created and an activation key for the new person is returned.

At this point, an Add Role request can be made to assign a role to this newly added person. See the section on Add Role for more details.

Add Person Processing

Step 1: Validation

When a request to add a person to the Registry is made, the Registry will first validate the request. If validation errors are found, a 400 code will be returned.

Step 2: Reconciliation

If no validation errors were found, the registry will perform a search to determine if the person that is being added is already in the Registry. This process is called reconciliation. There are three possible outcomes:

  1. No matches are found
  2. An exact match is found
  3. One or more partial matches are found

It should be noted that the Add Person Request not only contains the information necessary to add a person to the registry, but also optionally contains additional information for reconciliation purposes. For example, the request may contain addresses, phone numbers, and email addresses. This data is not Person data and will be used for reconciliation only. Non Person data is not persisted when the person is added.

No Matches Are Found

When no matches are found, the Registry will add the person to the Registry, create the preferred identifier and will return an activation key for the new person. A 201 code is returned.

At this point, an Add Role request can be made to assign a role to this newly added person. See the section on Add Role for more details.

Exact Match Found

An exact match is when reconciliation finds one person in the Registry that matches the specified criteria. There are two cases to be aware of for the exact match case:

  1. SoR attempting to add the person is same SoR that added the person found in the Registry.
  2. SoR attempting to add the person is not the same SoR that added the person found in the Registry.

In the first case, the add request is an error, since the SoR should not be trying to add the same person twice. The add person request will return 409 and an error message.

In the second case, the resource will return HTTP 303 which means that the exact match is found and the client should follow a link to a returned resource to further examine it.

Sample Response:

HTTP/1.x 303 See Other
https://test-registry.rutgers.edu/api/v1/people/NETID/JC01

At this point, an Add Role request can be made to assign a role to the person. See the section on Add Role for more details.

One or more possible matches are found

If reconciliation finds people in the Registry which partially match the criteria used for reconciliation, reconciliation will return the partial matches that were found. For example, if the add request tries to add a person with the same last name and same phone number as someone already in the registry, a 409 code will be returned along with links for the partial matches.

Sample Response:

HTTP/1.x 409 Conflict
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<open-registry-resources>
<link href=https://dev-registry.rutgers.edu/api/v1/people/NETID/JC01 rel="person"/>
</open-registry-resources>
Content-Type: application/xml

When the Add Person Request returns partial matches, the calling application has several possible ways to respond:

  1. Indicate that the person to be added is not any of the returned partial matches and should be added to the Registry. (Force Add)
  2. Indicate that the person to add is in fact one of the persons returned in the list of partial matches. (Link to Existing Person)
Force Add

For the first case, person is not a match for any of the partial matches, the following request can be issued to add the person in the Registry:

https://test-registry.rutgers.edu/api/v1/sor/443/people?force=y

POST /api/v1/sor/443/people?force=y HTTP/1.1
Host: test-registry.rutgers.edu
Content-Type: application/xml
Authorization: Basic cmF0czpSQVQxMjM0
<?xml version="1.0"?>
<open-registry-person sor-person-id="124">
    <dob>1967-09-23</dob>
    <ssn>035551478</ssn>
    <gender>F</gender>
    <names>
       <name type="FORMAL" first="Cindy" last="Simon" />
    </names>
</open-registry-person>

Sample Response:

HTTP/1.x 201 Created
Location: [https://test-registry.rutgers.edu/api/v1/people/NETID/JC02]
Content-Type: application/x-www-form-urlencoded

activationKey=Pl6ZcOej

If validation errors are found, then 400 is returned.
If no validation errors are found, the person is added. A 201 code is returned indicating that the person was successfully added to the registry. The preferred identifier, in this case NetID, is created and an activation key for the new person is returned. At this point, an Add Role request can be made to assign a role to this newly added person.

Link to Existing Person

For the second case, the calculated person is a match for one of the partial matches. The subsequent request would be to 'link' the SoR record for that SoR with the chosen calculated person:

https://test-registry.rutgers.edu/api/v1/people/NETID/JC01

POST /api/v1/people/NETID/JC01 HTTP/1.1
Host: test-registry.rutgers.edu
Content-Type: application/xml
Authorization: Basic cmF0czpSQVQxMjM0

<?xml version="1.0"?>
<open-registry-person sor="123" sor-person-id="124">
    <dob>1967-09-23</dob>
    <ssn>035551478</ssn>
    <gender>F</gender>
    <names>
       <name type="FORMAL" first="Cindy" last="Simon" />
    </names>
</open-registry-person>

Sample Response:

HTTP/1.x 204 No Content

If validation errors are found, a 400 code is returned.
If the person cannot be linked to an existing person, a 409 code is returned.
If the SoR record is successfully added, a code of 204 is returned.

Adding Roles

Roles can be assigned to people in the Registry. The following is an example of adding the role "CGSFM" to person identified by the Source of Record 123 as person 124:

https://test-registry.rutgers.edu/api/v1/sor/123/people/124/roles

POST /api/v1/sor/123/people/124/roles HTTP/1.1
Host: test-registry.rutgers.edu
Content-Type: application/xml
Authorization: Basic cmF0czpSQVQxMjM0

<?xml version="1.0"?>
<open-registry-role title="Associate Professor" affiliation="Faculty" start-date="2009-01-02" end-date="2011-05-22" percentage="100" sponsor-id="DCEO" sponsor-type="ORG_UNIT" organizational-unit="10110" system-of-record="TEST">
	<addresses>
		<address type="HOME">
			<line1>225 Main st.</line1>
			<line2>distr.</line2>
			<city>Main City</city>
			<postal-code>70097</postal-code>
			<country-code>US</country-code>
			<region-code>NJ</region-code>
		</address>
		<address type="CAMPUS">
			<line1>5 Main ave</line1>
			<city>New Brunswick</city>
			<postal-code>08887</postal-code>
			<country-code>US</country-code>
			<region-code>NJ</region-code>
		</address>
	</addresses>

	<emails>
		<email type="HOME" address="jane@gmail.com"/>
		<email type="CAMPUS" address="jc@example.com"/>
	</emails>
	<phones>
		<phone type="LANDLINE" address-type="HOME" phone_line_order='1'>
			<country-code>1</country-code>
			<area-code>908</area-code>
			<number>787-7654</number>
		</phone>
		<phone type="CELL" address-type="CAMPUS" phone_line_order='1'>
			<country-code>1</country-code>
			<area-code>908</area-code>
			<number>123-4567</number>
			<extension>556</extension>
		</phone>
	</phones>
</open-registry-role>

Sample Response:

HTTP/1.x 201 Created
Location: https://test-registry.rutgers.edu/api/v1/sor/123/people/124/roles/555

In the example above, the return code is 201 indicating that the person 124 was found and the role was successfully added.

If the person was not found, 404 is returned.

If validation errors are found 400 is returned.

Please see the following for a detailed listing of return codes for Add Person and Add Role:

http://www.ja-sig.org/wiki/display/ORUM/SoR+Person+Resource

http://www.ja-sig.org/wiki/display/ORUM/SoR+Role+Resource