Subscription Client Testing Process

❗	Warning: This page is going to be retired and this documentation will be maintained at - https://github.com/OpenConceptLab/ocl-docs/blob/main/docs/source/oclapi/technical/subscriptions.md

Table of Contents

Overview

• Overview

Subscription Testing Process

• Process

Overview

This page outlines a step-by-step process for testing all key functionality of OCL from the point of view of a Subscription Client -- that is, any external software/module that will connect to OCL via the API to fetch exports and source updates, and perform basic content updates. Note that there may be additional functionality performed by the subscription client, such as an import or logging, that should be tested in addition to the steps outlined below.

A note on Source Versions

Also note about source versions:  Unfortunately source versions were not implemented to spec (meaning, they work differently than Github tags) -- so they need a bit of explanation. 

• First, the most recent source version is a container of all edits that you make until you create a new source version. Originally, source versions were supposed to be a frozen snapshot in time (like Github tags), but there was something lost in translation with the developer. Meaning, that to create a snapshot that does not change, you must create a new source version (let's call it v9) and then create an additional version (v9-head) which will effectively freeze v9 and cause v9-head to contain all subsequent edits until a new source version is created.
• Second, only one source version can be "released" per source (this will be changed in the future).
• Third, source versions should always be created with previous_version ID set to the most recent source version and with released = false -- not doing so can corrupt the entire source.

Process

1. Manually create user account on OCL to get an API token
   • From OCL website, sign up for new OCL user account
   • From your email account, verify your new account
   • Sign-in to OCL using your new account and browse to your user profile (link is at the top-right)
   • Record your user's API token from your user profile page
2. Create a new organization and source
   • Create new org (e.g. "MyOrg") using the "+" dropdown at top-right -- or using the API:

     POST /orgs/

     {
         "id": "MyOrg",
         "full_name": "My Organization"
     }
     

   • Create new source (e.g. "MySource") using the "Add Source" link on your organization's page -- or from API:

     POST /orgs/MyOrg/sources/
     

     {
         "id": "MySource",
         "full_name": "My Source"
     }
     

3. Populate your new source with some starter content
   • Add minimum of 3 concepts to test the different types of concept edits (New, Update, Delete/Retire, No Change) -- can do this on the OCL website using the "Add Concept" link on the source page, or via the API:

     POST /orgs/MyOrg/source/MySource/concepts/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/concepts/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/concepts/
     

     {
     }
     

   • Add minimum of 6 mappings, 1 internal and 1 external mapping per concept, to test the different types of mapping edits (Create, Update, Delete/Retire, No Change) for both internal and external mappings -- can do this on the OCL website using the "Add Mappings" link on individual concept pages, or via the API:

     POST /orgs/MyOrg/source/MySource/mappings/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/mappings/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/mappings/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/mappings/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/mappings/
     

     {
     }
     

     POST /orgs/MyOrg/source/MySource/mappings/
     

     {
     }
     

4. Create new source versions to save the current state of the source and prepare for export
   • Fetch the automatically created source version and record ID

     GET /orgs/MyOrg/sources/MySource/versions/
     

     {
         # source version output goes here
     }
     

   • Create first new source version setting `previous_version` to `id` from above

     POST /orgs/CIEL/sources/CIEL/versions/
     

     {
         "id":"v1.0",
         "previous_version": "5582be2550d61b5538ed694c",
         "description": "CIEL Dictionary release 2015-05-14",
         "released": false
     }
     

   • Verify that source version `v1.0` has finished processing -- `_ocl_processing` should be `false` or null/not returned

     GET /orgs/CIEL/sources/CIEL/v1.0/
     

     {
         "id":"v1.0",
         ...
         "_ocl_processing": false
     }
     

   • After `v1.0` has finished processing, create a second new source version called `v1.1` setting `previous_version` to the `id` from the one you just created - this effectively freezes `v1.0` and all new changes will be saved to `v1.1`

     POST /orgs/CIEL/sources/CIEL/versions/
     

     {
         "id":"v1.1",
         "previous_version": "v1.0",
         "description": "My Source v1.1 -- under development",
         "released": false
     }
     

   • Now release `v1.0`

     POST /orgs/CIEL/sources/CIEL/v1.0/
     

     {
         "released": true
     }
     

5. Cache export of the newly released export version
   • Create and cache the export of source version `v1.0`

     POST /orgs/MyOrg/sources/MySource/v1.0/export/
     

6. Make changes to concepts and mappings - these will be saved to source version `v1.1`
7. Fetch the export and changes made since the export
   • Fetch the export - the request returns the URL to download the export file in the header attribute `exportUrl`

     GET /orgs/MyOrg/sources/MySource/v1.0/export/
     

   • Fetch changes to source since the export using the lastUpdated timestamp from the export file as an ISODate

     GET /orgs/MyOrg/sources/MySource/?includeConcepts=true&includeMappings=true&updatedSince=[:LastUpdatedTimestamp-as-ISODate]
     

8. Test the subscription client configuration and initial synchronization
   • Subscription Client Configuration
   • Initial Synchronization
9. Make additional updates to concepts and mappings to test subsequent synchronization of the subscription module
   • Make some concept changes
   • Make some mapping changes
10. Test the subscription client subsequent synchronization
    • Perform subsequent synchronization