API Source is an External Identity Source Plugin designed to integrate with upstream sources via a REST API.

The data format used by this Plugin is based on the TAP Attribute Dictionary. As such, while the COmanage-specific term External Identity Source is generally used in this documentation, the TAP term System of Record is used when referencing elements directly related to the TAP definitions. Practically speaking, these terms can be used interchangeably.

Configuration

  1. API Source is part of the ApiConnector Registry Plugin, which must be activated.
  2. When adding a new External Identity Source, the Plugin is ApiConnector.ApiSources.

Modes

API Source supports three modes of operation:

  • Push Mode: The External Identity Source sends records to API Source via a standard API
  • Pull Mode: API Source queries the External Identity Source via the EIS's API (not yet implemented)
  • Poll Mode: API Source polls an endpoint (typically a message bus) for records to process (not yet implemented)

Push Mode

Push Mode requires the creation of an API User. The specified API User will have read/write access to the API Source API, the endpoint of which is made available via the API Source configuration page. It is recommended to create an Unprivileged CO API User for this purpose, though any defined API User may be used.

Endpoints and Actions

Push Mode

The URL prefix for ApiSource operating in Push Mode is

https://server.org/registry-pe/api/apisource/apisourceid/v2/sorPeople/sorlabel/sorid

where

  • apisourceid: The API Source ID for this instance of API Source
  • sorlabel: The System of Record Label, as configured for the External Identity Source instance (the Plugin's Edit or Propertiespage)
  • sorid: The System of Record's unique ID for the record being presented

apisourceid and sorlabel are used to find the correct instantiation of ApiSource. The exact URL is available from the API Source Configuration page. Within Registry, the sorid is referred to as source_key.

The following actions are supported in Push Mode:

  • DELETE: Remove the specified record from the set of records associated with this SoR. No body is expected.
  • GET: Obtain the current record for the specified SOR ID. The response will be a record in the same format as was PUT.
  • PUT: Add a record for the specified SOR ID, or update an existing record. The body of the request is in the message format described below.

The following HTTP Response Codes may be returned:

  • 200: An existing record was found and deleted, returned, or updated (as appropriate for the action).
  • 201: The record was successfully stored and processed (PUT only).
  • 202: The record was accepted, but further processing (and possibly administrator action) is required.
  • 401: Unauthenticated / authorization failed.
  • 404: The specified record does not exist (DELETE or GET only).
  • 500: An error occurred.


The Response Codes are based on the API Source message itself. So, for example, if a new record is sent via API Source that matches via the Pipeline configuration to an existing Person, the result will be a 201 response due to the new API Source Record, and not 200 (for the existing Person).

Message Format

The message body for all API Source transactions is defined in this JSON Schema file.

PUT (Request)

The request must include both Content-Type and Accept headers with values of application/json. See Request Headers for more information.

Formatting Notes

Deleting Single Value Attributes

In order to delete a single valued attribute such as title or validFrom, send a blank value (not null, and do not omit the attribute entirely). For example

        "roles": [
            {
				"roleIdentifier": "1",
				"status": "A",
		        "affiliation": "faculty",
        		"organization": "School of Philosophy and Biopharmacology",
		        "department": "Department of Metaphysics",
        		"title": "Associate Professor of Metaphysical Microbiology",
		        "validFrom": "2019-09-01T00:00:00",
        		"validThrough": ""
             }
        ]

Role Identifier

The Role Identifier need only be unique within the External Identity, it does not need to be unique across all records from the External Identity Source. Note the use of the attribute roleIdentifier in the message format (to align with the standard API terms) for what the Registry data model calls role_key.

Status

The status field must be specified using the enumeration value (the one or two character code as listed in the JSON Schema definition), not the english language word. These values are:

  • A: Active
  • D: Archived
  • D2: Duplicate
  • GP: Grace Period
  • S: Suspended

For more information on External Identity Role status, see Data Model Considerations.

Example Message

{
    "sorAttributes": {
        "names": [
            {
                "type": "official",
                "given": "Pat",
                "middle": "X",
                "family": "Lee"
            }
        ],
        "dateOfBirth": "1990-04-25",
        "identifiers": [
            {
                "type": "national",
                "identifier": "541-00-3732"
            }
        ],
        "emailAddresses": [
            {
                "type": "personal",
                "address": "patxlee@email.nil",
                "verified": true
            }
        ],
        "addresses": [
            {
                "type": "home",
                "streetAddress": "3593 Red Maple Drive",
                "locality": "Los Angeles",
                "region": "CA",
                "postalCode": "90046",
                "country": "US"
            }
        ],
        "telephoneNumbers": [
            {
                "type": "home",
                "number": "323-555-1208"
            }
        ],
        "urls": [
            {
                "type": "personal",
                "url": "https://metaphysics.spb.ac.nil/plee"
            }
        ],
        "adhoc": [
            {
                "tag": "flavor",
                "value": "chocolate"
            }
        ],
        "roles": [
            {
				"roleIdentifier": "1",
				"status": "A",
		        "affiliation": "faculty",
        		"organization": "School of Philosophy and Biopharmacology",
		        "department": "Department of Metaphysics",
        		"title": "Associate Professor of Metaphysical Microbiology",
		        "validFrom": "2019-09-01T00:00:00",
        		"validThrough": "2020-08-31T23:59:59",
		        "managerIdentifier": "E79725186",
        		"sponsorIdentifier": "E69813130",
             }
        ]
    },
    "returnUrl": "https://registry.myvo.org/localapps/post-enrollment?regid=12345"
}

See Also

Changes From Earlier Versions

As of Registry v5.0.0

  • Message Meiosis is no longer supported, as the native data structures now permit multiple Roles.
  • Time specifications no longer use the Z notation. Strictly speaking this is not compliant with the TAP API, and is subject to change in a future release (CFM-352).
  • No labels