Versions Compared

Version Old Version 1 New Version 2
Changes made by

Vicki McEwen

Vicki McEwen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Expand
titleTable Of Contents
Table of Contents
stylenone

Introduction

Last Updated 11/21/24

This document provides a detailed mapping between the properties of the JSON response and the NextGen API schema
for the Mandate Extraction and Analysis API. The goal is to demonstrate how each property in the utilized Legacy Services API JSON
response corresponds to properties in the NextGen JSON schema, facilitating a smooth transition and integration.

General Overview

The legacy Services APIs all require you to create

  • Legacy Services API Approach: Requires creating a Shared Authority Document List and

then invoke the

  • invoking APIs using the

unique

  • List ID or Authority Document ID.

The response included the Authority Document’s metadata and all its

  • Returns all Authority Document metadata, Citations, Mandates, and Common Controls in a single payload.

In Nextgen APIs, there is no need to create a

  • New NextGen API Approach: Eliminates the need for Shared Authority Document

List

  • Lists.

Instead,

  • Authority Document metadata, Citations, Mandates, and Common Controls are accessed through separate, dedicated endpoints.

The following is a mapping of the Legacy Services API Endpoints to the NextGen API Endpoints:

Example:

  • Legacy Services API: /authority-document/:id/details (Returns all related data in one response)

  • New NextGen API:

    • /authority-document/:id (Metadata)

    • /authority-document/:id/citation (Citations)

    • /authority-document/:id/mandate (Mandates)

    • /authority-document/:id/control (Common Controls)

Backward Compatibility: Legacy (CCH) Authority Document IDs

You can retrieve Authority Documents using legacy IDs via the /authority-document/legacy/:id endpoint to fetch the new elementid for subsequent API calls.

  • Retrieve Authority Document by Legacy ID

    • GET /authority-document/legacy/:id

      • Path Variables:

        • :id : The legacy CCH elementId

    • This endpoint returns the NextGen Authority Document ID and and legacy ID.

    • The NextGen AD ID is required for all subsequent API requests (to retrieve metadata, citations, mandates & controls)

Furthermore, when retrieving the metadata of an authority document from NextGen, the legacy CCH elementId will be returned as a property.

  • MetaData Example: For example:

Code Block
languagejson
{
    "@context": "URL",
    "@id": "URL",
    "@type": "string",
    "elementId": "string",
    "schemaVersion": "string",
    "authorityDocumentType": "string",
    "officialName": "string",
    "legacyId": "string",
    .........
}

Endpoint & Property Mapping

  • Legacy Services API: Properties from the CCH Services API JSON response.

  • New NextGen JSON: Corresponding properties in the NextGen API schema.

  • Notes: Additional information or context about the mapping.

Endpoints

Function

Legacy Services API

NextGen API

CommentNotes

Get Account Information

/my-account

/my-account

Returns information about the account.

Search for Authority Documents

Not Available

/authority-document?page=1&perPage=100&search=<value>

Returns documents containing the search term. Optionally remove the search parameter to retrieve all documents.

Retrieve Authority Document

/authority-document/:document-id/details

/authority-document/:id

Legacy returns the document metadata, all citations, all mandates and all controls. NextGen only returns the document metadata.

Search for Citations in a document

Not Available

/authority-document/:id/citation?page=1&perPage=100&search=<value>

Returns citations containing the search term. Optionally remove the search parameter to retrieve all citations for the document.

Retrieve a specific Citation

Not Available

/authority-document/:id/citation/:citationId

NextGen can retrieve specific citations within a document

Search for Mandates in a document

Not Available

/authority-document/:id/mandate?page=1&perPage=100&search=<value>

Returns mandates containing the search term. Optionally remove the search parameter to retrieve all mandates for the document.

Retrieve a specific Mandate

Not Available

/authority-document/:id/mandate/:mandateId

NextGen can retrieve specific mandates within a document.

Search for Controls in a document

Not Available

/authority-document/:id/control?page=1&perPage=100&search=<value>

Returns controls containing the search term. Optionally remove the search parameter to retrieve all controls for the document.

Retrieve a specific Common Control

Not Available

/authority-document/:id/control/:controlId

NextGen can retrieve specific controls within a document

Retrieve all Common Controls for a list of Authority Documents

/cch-ad-list/:list-id/tracked-controls/details

/authority-document/:id/control?page=1&perPage=100

Legacy returns all common controls for all documents in the list. For NextGen, retrieve all of the controls for one document at a time.

Legacy (CCH) Authority Document IDs

In the NextGen system, all Authority Documents are assigned a new elementId. However, you can still retrieve an Authority Document in NextGen using legacy IDs, for backward compatibility using the GET /authority-document/legacy/:idendpoint.

  • Retrieve Authority Document by Legacy ID

    • GET /authority-document/legacy/:id

      • Path Variables:

        • :id : The legacy CCH elementId

    • This endpoint returns the NextGen Authority Document ID and and legacy ID.

    • The NextGen AD ID is required for all subsequent API requests (to retrieve metadata, citations, mandates & controls)

Furthermore, when retrieving the metadata of an authority document from NextGen, the legacy CCH elementId will be returned as a property.

  • MetaData Example: For example:

Code Block
languagejson
{
    "@context": "URL",
    "@id": "URL",
    "@type": "string",
    "elementId": "string",
    "schemaVersion": "string",
    "authorityDocumentType": "string",
    "officialName": "string",
    "legacyId": "string",
    .........
}

Detailed Property Mapping

  • Legacy Services API Property: Properties from the CCH Services API JSON response.

  • New NextGen JSON Property: Corresponding properties in the NextGen API schema.

    • Notes: Additional information or context about the mapping

    .

    Top-Level Properties

    JSON Property Mapping Matrix

    Legacy Services API

    New NextGen

    Notes

    live

    coreMetaData.live

    Indicates if the mandate is active.

    deprecated_by

    coreMetaData.deprecatedBy

    URL indicating what deprecated the mandate.

    deprecation_notes

    coreMetaData.notes

    Additional notes on deprecation.

    time_created

    coreMetaData.created.timeStamp

    Timestamp when the mandate was created.

    date_added

    coreMetaData.created.timeStamp

    Date when the mandate was added.

    time_updated

    coreMetaData.modified.timeStamp

    Timestamp when the mandate was last updated.

    date_modified

    coreMetaData.modified.timeStamp

    Date when the mandate was modified.

    language

    language.name

    Language of the mandate (e.g., "eng").

    license_info

    license.url

    URL to the license terms.

    sort_value

    hierarchyItems.sortValue

    Used for sorting mandates.

    genealogy

    hierarchyItems.hierarchicalParents

    Represents the hierarchical lineage.

    sort_id

    hierarchyItems.sortPath

    Calculated value for quick sorting

    reference

    primaryCitation.reference

    The citation reference string.

    guidance

    primaryCitation.taggedText.text

    The primary citation text the mandate is derived from.

    guidance_as_tagged

    taggedText.text

    The mandate text (Full text of primary citation, additional citation, and additional guidance in current system).

    is_audit_question

    -

    -

    id

    elementId

    Unique identifier for the mandate (Not a direct mapping).

    authority_document

    authorityDocument

    Object representing the source document.

    control

    matchedControl.control

    Object representing the matched control.

    audit_item

    -

    -

    asset

    -

    Asset information related to the control.

    compliance_document

    -

    -

    role

    -

    -

    data_content

    -

    Data content information.

    organizational_function

    -

    Organizational function related to the control.

    record_example

    -

    -

    metric

    -

    -

    monitored_event

    -

    -

    organizational_task

    -

    Organizational task information.

    record_category

    -

    -

    configurable_item_with_settings

    -

    -

    sentence

    taggedText

    Main text of the mandate with annotations.

    parent

    hierarchyItems.hierarchicalParents

    Parent mandates in the hierarchy.

    check_digit

    coreMetaData.checksum

    Used for validation of response data (Not a direct mapping).

    Nested Objects

    Authority Document

    JSON Path

    • Legacy Services API: authority_document

    • New NextGen: authorityDocument

    JSON Property Mapping Matrix

    Legacy Services API

    New NextGen

    Notes

    id

    authorityDocument.elementId

    Identifier for the document (Not a direct mapping).

    _href

    authorityDocument.@id

    URL to the document details (Not a direct mapping).

    Control

    JSON Path

    • Legacy Services API: control

    • New NextGen: matchedControl.control

    JSON Property Mapping Matrix

    Legacy Services API

    New NextGen

    Notes

    live

    coreMetaData.live

    Indicates if the control is active.

    deprecated_by

    coreMetaData.deprecatedBy

    URL indicating what deprecated the control.

    deprecation_notes

    coreMetaData.notes

    Notes on deprecation.

    time_created

    coreMetaData.created.timeStamp

    Creation timestamp.

    time_updated

    coreMetaData.modified.timeStamp

    Last update timestamp.

    language

    language.name

    Language of the control.

    license_info

    license.url

    License information URL.

    name

    control.name

    Name of the control.

    impact_zone

    control.impactZone.name

    Impact zone classification.

    type

    control.controlType.name

    Type of the control.

    classification

    control.classification.name

    Classification of the control.

    sentence

    control.taggedText

    Control's text with annotations.

    parent

    hierarchyItems.hierarchicalParents

    Parent controls in the hierarchy.

    id

    control.elementId

    Unique identifier for the control (Not a direct mapping).

    _href

    control.@id

    URL to the control details (Not a direct mapping).

    Sentence

    JSON Path

    • JSON Path: sentence

    • NextGen JSON Path: taggedText

    JSON Property Mapping Matrix

    Legacy Services API

    New NextGen

    Notes

    sentence

    taggedText.text

    The raw text of the mandate.

    tagged_phrases

    taggedText.taggedTerms

    Annotated terms within the text.

    live

    coreMetaData.live

    Indicates if the sentence is active.

    time_created

    coreMetaData.created.timeStamp

    Creation timestamp.

    time_updated

    coreMetaData.modified.timeStamp

    Last update timestamp.

    id

    taggedText.elementId

    Unique identifier for the tagged text (Not a direct mapping).

    correct

    -

    -

    Tagged Phrases

    JSON Path

    • Legacy Services API: sentence.tagged_phrases

    • New NextGen: taggedText.taggedTerms

    JSON Property Mapping Matrix

    Legacy Services API

    New NextGen

    Notes

    start

    Derived from tokens.start

    Start index of the term in the text.

    end

    Derived from tokens.end

    End index of the term in the text.

    nonstandard

    term.nonstandard

    Indicates if the term is nonstandard.

    id

    taggedTerm.elementId

    Unique identifier for the tagged term (Not a direct mapping).

    sentence.id

    taggedText.elementId

    Unique identifier for the tagged text (Not a direct mapping).

    type.name

    taggedType.name

    Classification of the term (e.g., "Primary Noun").

    term

    term

    Contains term details such as name and lemma.

    definition

    definition.text

    Textual definition of the term.

    language

    language.name

    Language of the term.

    license_info

    license.url

    License information URL.

    Info

    Note: The tokens property in taggedTerm references the tokens in taggedText.tokens array. The startand end indices help identify the specific tokens associated with the term.