tipp_dto

A number of functions in gokb now require a tipp to be described using external references. These tipp DTO objects can compose the inbound or outbound components of a package. Most importantly, they can be "Marked Up" with problems and error reports. it is critical that we validate tipp level data before processing it. This page sets out the canonical tipp record, and indicates where and how it can be marked up in the event of validation errors

{
  title_reference:{
    internalId:Long,        /* Optional - if used, don't supply the following */
    title:'String title',   /* Mandatory if not using internalId */
    first_author:'FA',      /* Optional, used in Mongraph Processing for title lookup */
    identifiers:[
      { type:'ns', value:'value' },
      { type:'ns', value:'value' }
    ]
  },
  platform_reference:{
    internalId:Long,        /* Optional - if used don't supply the following */
    name:'String Name'      /* Mandatory if ID not specified */
    identifiers:[
      { type:'ns', value:'value' },
      { type:'ns', value:'value' }
    ]
  },
  package_reference:{
    internalId:Long,        /* Optional - if used don't supply the following */
    name:'String Name'      /* Mandatory if ID not specified */
    identifiers:[
      { type:'ns', value:'value' },
      { type:'ns', value:'value' }
    ]
  },
  coverage_data:[
    { 
      startDate:'',
      startVolume:'',
      startIssue:'',
      endDate:'',
      endVolume:'',
      endIssue:'',
      coverageDepth:'',
      coverageNote:'',
      embargo:''
    },
    {Repeat above for each coverage block}
  ]
}

Ingest rules

The primary processing point for this structure is the validateTippDTO and upsert methods in org.gokb.cred.TitleInstancePackagePlatform. Ideally moving forward, all tipp processing should be handled by reusing/extending the structure defined above and enhancing this method.

Transaction Control

The upsert method must take it's transaction from the parent context and not create it's own transactional context. If a caller wishes to isolate a specific call to upsert it is it's own responsibility to create the context and call upsert within that context.

Validation

TIPP upsert processing must not progress unless validation of the dto completes successfully. It is the callers responsibility to call validateTippDTO before calling upsert. Callers may wish to validate an entire package before calling upsert on that package, therefore upsert cannot itself validate. The method

public static boolean validateTippDTO(tipp_dto) 

Should return a boolean if the tipp_dto is valid and false otherwise. If false, the dto should be modified with messages and indications of the problem.

Specific Validation : Titles

tipp_dto objects MUST describe a title which is valid and exists in the gokb system, otherwise the tipp is not valid. Callers looking to ingest packages will, therefore, need to create any titles before calling upsert on a tipp. There are a number of reasons for this but primarily separation of concerns - creating title objects is a heavyweight process both in terms of processing and functionality. This functionality belongs in the TitleInstance domain class and not in the TIPP.

Specific Validation: Packages and Platforms

Similarly, tipp_dto objects must reference packages and platforms which already exist in the system. If they cannot be looked up, the package is invalid. Callers should take steps to create any referenced objects before calling validate/upsert.

Processing

TIPP Upsert is a process of dereferencing the title, package and platform reference sections, and then consuming the various coverage statements set out in the dto. Since dependent objects must exist processing should be simple calls to the respective lookup functions. Any failure to resolve a reference is a a fatal error and results in an exception.

Coverage note processing

..