# CJaaS Reference Notes

## Questions and Items to Clarify
- **Ram** - Is trycjaas.exp.bz/swagger/ui the beset resource and more up to day? Does it automatically reflect any API changes in real time?
- **Ram or Venki** Why do we use a POST request and send a data template? Why not just a GET? _**Answer**: because it enables dictating the shape of the data that comes back from the backend, rather than a static shape for all users_

## Test User Accounts
Keep track of User ID info that we can use to test API requests.
Please add any known references, or links to API resources.

560018-Venki
560021-Venki
??????-Yana

### Request Template and API Response (for dummies)
The Profile View data request has some idiosyncratic behaviors to achieve the fuller functionality that CJaaS aims to provide. Because the shape of the data must serve any imaginable use case, the API cannot serve back any static opinionated shape, and therefore the front End cannot be built upon some assumed JSON structure.

Instead, there is a handshake and merge between the 2 JSON forms. The Client-side submits esentially an "empty form" via POST that lists the kinds of events it wants and which data points about those events to send back. The API fills in the blanks and returns the actual data.

#### An example POST data body, sent in the request to the API:

{
  Name: "Request Template",
  DatapointCount: 1000, // "I want up to this many results"
  Attributes: [
    { // DATA POINT 1
      Version: "0.1",
      Event: "Quote", // "From the Quote Events . . . "
      Metadata: "email", // "I want the email data point . . ."
      DisplayName: "Email",
      AggregationMode: "Value",
      type: "tab", // "To occupy a "tab" type front-end role"
      tag: "email",
      Limit: 1,
    },
    {
      Version: "0.1",
      Event: "Quote", // "From the Quote Events . . . "
      Metadata: "firstName", // "I want the firstName data point . . ."
      DisplayName: "First Name",
      Limit: 1,
      AggregationMode: "Value",
      tag: "name",
      type: "inline", // "To occupy a "inline" type front-end role"
    },
    {
      Version: "0.1",
      Event: "Quote", // "From the Quote Events . . . "
      Limit: 1,
      Metadata: "zipCode", // "I want the zipCode data point . . ."
      DisplayName: "Zip Code",
      AggregationMode: "Value",
      type: "table", // "To occupy a "inline" type front-end role"
    },
  ]
}

#### Which will receive a return like this:

{
    "name": "Request Template",
    "customerId": "560021-V3nki",
    "generatedAt": "2021-04-05T17:21:56.980636Z",
    "attributeView": [
        {
            "queryTemplate": { // MetaData about the Event type and request
                "version": "0.1",
                "event": "Quote",
                "metadata": "email",
                "limit": 1,
                "displayName": "Email",
                "aggregationMode": "Value",
                "verbose": true
            },
            "result": "[e-mail]", // Actual Datapoint!
            "journeyEvents": "[{\"data\":{\"firstName\":\"Venki\",\"lastName\":\"V\",\"email\":\"[e-mail]\"},\"datacontenttype\":\"application/json\",\"id\":\"b04f0d16-0778-4728-831f-73732f15dd54\",\"person\":\"560021-Venki\",\"source\":\"Website\",\"specversion\":\"1.0\",\"time\":\"2021-03-15T07:06:48.355Z\",\"type\":\"Quote\"}]"
            // And journeyEvents, for more detailed data stream
        },
        {
            "queryTemplate": { // MetaData about the Event type and request
                "version": "0.1",
                "event": "Quote",
                "metadata": "firstName",
                "limit": 1,
                "displayName": "First Name",
                "aggregationMode": "Value",
                "verbose": false
            },
            "result": "we", // Actual Datapoint!
            "journeyEvents": null 
        },
        {
            "queryTemplate": { // MetaData about the Event type and request
                "version": "0.1",
                "event": "Quote",
                "metadata": "zipCode",
                "limit": 1,
                "displayName": "Zip Code",
                "aggregationMode": "Value",
                "verbose": false
            },
            "result": "", // MetaData about the Event type
            "journeyEvents": ""
        },
    ]
}

***NOTE*** The `type`, `tag`, and `displayName` keys passed to the server are for client-side reference only, and do not exist as data points in the API.
***What's happening with them?*** When the ProfileView Widget from CJaaS Widgets executes it's Profile Data fetch, it maps the data request template and the API response data into a single merged JSON form that includes the server's data and Clinet-side opinion on data that belongs in a `tab`, `table`, or have a particular `displayName` . . etc. It provides an interface for the front-end developer to dictate the final shape for presentation layer rendering.

<hr/>

#### CJaaS API explorer:
https://trycjaas.exp.bz/swagger/ui
~~or here? https://cjaasplayground-edge.azurewebsites.net/swagger/ui~~ this one does not have `v1`

_I don't know about you but I always feel like I struggle to get my API URL's figured out or rembered well, so this would be a great thing to have ready to go. I'm also just getting confused as to where the latest API docs really are, there are 2 playgrounds, but I don't know what's the source of truth_

## CJaaS build/release/publish

#### Common Components
- Presentational use.
- Assume data structure.
- These components do not make API requests, they only present data that is passed to them.
- NPM Package
- ***KEVIN: Add CONTRIBUTING doc for Cisco Employees that explains the need to authenticate with npm:auth via uuip-publish and you need to be in the cjaas org on npmjs***

#### Widgets
- They use common components to presnt data and they execute business logic and make API requests to CJaaS API endpoints
- **THIS** is the primary place to update APIs when changes happen
- Collection of standalone projects. They all need to be deployed individually

<hr />

# Contributing

1. Create a peronsal NPMJS Account (If you don't have one yet)
https://www.npmjs.com/

2. Navigate to the root of `cjaas-common-components`

3. Install UUIP-Publish globally (should only have to do this once)
`yarn global add uuip-publish`

4. Authenticate with your Cisco credentials (generates `.npmrc` file)
`npm run npm:auth`

5. Authenticate with NPMJS (with your personal npmjs credentials)
`npm login`

6. Before you publish, ensure that you have updated the `package.json` version to what what you want the next npm version to be.

  "name": "@cjaas/common-components",
  "version": "1.2.1-dev.3",

7. Now npm:publish (need to be on the Cisco VPN)
`yarn npm:publish`

8. Now you should see a new folder called
`cjaas-common-components/publish`

9. If you experience an error while publishing...

a. Remove the following code in `publish/package.json`

    "publishConfig": {
       "registry": "https://engci-maven.cisco.com/artifactory/api/npm/unified-ui-platform-npm-local/"
    }

b. `cd publish`

c. `npm publish`

d. Verify the version updated on the npmjs site
https://www.npmjs.com/package/@cjaas/common-components

### Resources
Github Common Components
https://github.com/CiscoDevNet/cjaas-common-components

NPMJS Common Components
https://www.npmjs.com/package/@cjaas/common-components

UUIP-Publish Repo
https://sqbu-github.cisco.com/Collaboration/uuip-publish

--------------------------

## Keys Discussion

There isn't a Tenant tha sees Organizations they are the same

"Services", not "organizations"

"Bot" is being used as consistent with Webex ("Services")
- Each Bot has a different key, because they have differnet lifecycles
- associate a key with a bot
- manage the lifelcycle of that key with the bot
- On the customer side
- Micro service paradigm
- E.G. a service/bot that GETs data and a service/bot that publishes with POST need different keys
- Services are also CJaaS name conventions like "data sink", "journey" etc.

CJaaS
Internal and External APIs
This UI calls internal APIs, purely accessible via Bots only

st=**demostore**&so=**sandbox**&ss=**datasink**&sp=**w&se**=2021-04-23T18:25:43.511Z&sk=**sandbox**&sig=TEUtd3qKp6pYjoTM7GEHDZeKRfnIWr90MQoW6r2xsB0=

CI only happens when a custome tries to access the admin portal, not when the "Bot" is used