COI - Project Integration with External System

Overview

The Kuali Research COI module has project integration with projects within the Kuali Research Sponsored Programs modules but there is also the capability to push projects into COI from a third party system.  Using the below configuration an institution could set up project data to push from a different system into Kuali Research COI disclosures.

Steps to Configure

1. In order to push a project from an external system into COI, we first need to set up the appropriate project type in the COI system and add associated statuses and roles. Please follow the steps in the COI - Configuration - Project Requirements article to set this up. 

2. For this exercise, we will assume we created a project with title ‘standalone project’. In order to push a project into COI, we need the Source System AKA Project Type Code and Source Status identifiers from the configuration of the ‘standalone project’ we created above. These values are autogenerated by the system. In order to retrieve this:

a. Use any tool, Postman or Curl or a script to make a GET call to retrieve the settings from the  REST endpoint at https://your-host-name/api/coi/fb/settings. An example of this is at https://greendale.kuali.co/api/coi/fb/settings . You will need a valid auth token of a system user to retrieve this information. Add this auth token to the request header such that the key is ‘Authorization’ and the value is formatted as ‘Bearer authToken’. This should retrieve a JSON which should have a `projectStatuses` property and a `projectTypes` property. These are a list of ALL project statuses and types in the system. From this array, you only want the statuses and types of the Project Type you created above. 

b. Project Types should be an array like this: 

"projectTypes": [

         {

             "reqDisclosure": true,

             "reporterAdded": false,

             "_id": "5d5dac202c19d8121666ef5e",

"typeCd": "1",

            "description": "Proposal",

             "newType": false

         },

         {

             "reqDisclosure": true,

            "reporterAdded": false,

            "requiredHierarchies": [],

            "_id": "5e8cf3dab6609f83b071c4fa",

             "description": "standalone project",

             "newType": false,

             "manual": true,

            "typeCd": "5e8cf3cad6f81eeb47fee333"

         }]

c. The Project Type Code we want, is the typeCd property of the element that has the same title as the project type you created above in step 1. In our case, this is the second element in the list, and its identifier is ‘5e8cf3cad6f81eeb47fee333’

d. In order to get the relevant status codes, look at the ‘projectStatuses’ property in the returned JSON. This should look like the following:

"projectStatuses": [

        {

            "reqDisclosure": false,

            "_id": "5d8a721693e76b115dfd8d80",

            "sourceStatusCd": "100",

            "projectTypeCd": "3",

            "description": "Pending/In Progress",

            "typeCd": 21

        },

    {

            "reqDisclosure": true,

            "_id": "5e8cf3dab6609f83b071c4ba",

            "sourceStatusCd": "5e8cf3dab6609f83b071c4a1",

            "description": "Active",

            "projectTypeCd": "5e8cf3cad6f81eeb47fee333"

        }]

The project statuses relevant to the project type we created in step 1. are all entries where ‘projectTypeCd’ is equal to ‘5e8cf3cad6f81eeb47fee333’. From these entries, get the ‘sourceStatusCd’ which are the identifiers that uniquely identify the source statuses. In our case we only have one status.

3. Now that we have the typeCode and sourceStatus code, we can create the JSON to push to COI. The following is a sample JSON structure of a project that can be pushed to COI. Some of the properties map as follows:

a. typeCode: The project type we obtained in step 2c.

b. sourceSystem: Is the same as the typeCode

c. sourceIdentifier: Is the unique identifier of the project in the source system, this is typically a number, for the Proposal Development module it is the proposal number, for Award,  it is the award number etc.

d. Source status is one of the status codes we obtained in step 2d. 

e. roleCode for the persons in the persons array are the role codes you entered for the roles in the project type configuration in step 1.

f. sourceUniqueIdentifier: Same as sourceIdentifier

All other properties are values obtained from your source system.

{

   "title": "test56",

   "typeCode": "5e8cf3cad6f81eeb47fee333",

   "sourceSystem": "5e8cf3cad6f81eeb47fee333",

   "sourceIdentifier": "56",

   "sourceStatus": "5e8cf3dab6609f83b071c4a1",

  "primeSponsorName": "NIH", 

   "primeSponsorCode": "002000",

   "persons": [

    {

       "sourceSystem": "5e8cf3cad6f81eeb47fee333",

      "sourceIdentifier": "56",

      "personId": "10000000001",

       "sourcePersonType": "EMPLOYEE",

       "roleCode": "PI",

       "metadata": {

        "sourceUniqueIdentifier": "56"

       }

    }

  ],

  "sponsors": [

     {

       "sourceSystem": "5e8cf3cad6f81eeb47fee333",

       "sourceIdentifier": "56",

       "sponsorCode": "002000",

       "sponsorName": "NIH",

       "metadata": {

         "sourceUniqueIdentifier": "56"

       }

     }

  ],

  "metadata": {

     "sourceUniqueIdentifier": "56"

   },

   "sponsorCode": "002000",

   "sponsorName": "NIH",

   "startDate": "2018-10-01",

   "endDate": "2018-10-31",

   "active": true

}

4. One you have this JSON, you can push this to COI using a REST API post call to the endpoint https://greendale.kuali.test/api/coi/projects . You will need an admin auth token or a service 2 service token to push this project. 

5. All subsequent changes to the project can be made by pushing the modified project ( Source System and Source Identifier are unique to the project so these cannot be changed. If they are, the system will create a new project as opposed to editing the existing one ) via a POST to the same endpoint.

Note: Some of the data shown in the project example below is optional. Here are the minimal required fields to push a project into Kuali COI sucessfully.

• active
• persons: Must include 1 person with the role code of PI
• sourceIdentifier
• sourceStatus
• sourceSystem
• sponsorCode
• sponsorName
• sponsors (with all other sponsor details included)
• title
• typeCode

Example JSON with all available attributes.

{
   "active": true,
   "awardTypeCode": 1,
   "awardTypeDescription": "Grant",
   "deactiviationReason": "reason why it was deactivated",
   "startDate": "Wed Dec 31 1969 18:00:00 GMT-0600 (CST)",
   "endDate": "Wed Dec 31 1969 18:00:00 GMT-0600 (CST)",
   "linkedProjects": [
      {
         "sourceIdentifier": "00000230",
         "sourceSystem": "KC-IP"
      },
      {
         "sourceIdentifier": "105",
         "sourceSystem": "KC-PD"
      },
      {
         "sourceIdentifier": "106",
         "sourceSystem": "KC-PD"
      }
   ],
   "noticeOfOpportunityCode": 1,
   "noticeOfOpportunityDescription": "Paper",
   "persons": [
      {
         "roleCode": "PI",
         "sourcePersonType": "EMPLOYEE",
         "personId": "10000000081",
         "sourceIdentifier": "000129-00001",
         "sourceSystem": "KC-AWARD"
      }
   ],
   "primeSponsor": {
      "sponsorCode": "000340",
      "sponsorName": "NIH",
      "sponsorTypeCode": "1",
      "sponsorTypeDescription": "Federal"
   },
   "shortUrl": "url to source system",
   "sourceIdentifier": "000129-00001",
   "sourceStatus": "1",
   "sourceSystem": "KC-AWARD",
   "sponsorCode": "000340",
   "sponsorName": "NIH",
   "sponsors": [
      {
         "sponsorName": "NIH",
         "sponsorCode": "000340",
         "sourceIdentifier": "000129-00001",
         "sourceSystem": "KC-AWARD",
         "sponsorTypeCode": "1",
         "sponsorTypeDescription": "Federal"
      }
   ],
   "title": "Cat Shock Therapy",
   "typeCode": "5"
}