# Migration Guide from 0.3.x to 0.5.x

## 1. Profile

Upgrade Profile with below. ==Please that `authURL`, `realm`, `clientId` are new keys we should add==.

baseURL: https://api.loc-cse.fst.network
namespace: saffron-cse

authURL: https://auth.us-west-2.fst.network/auth
realm: loc-cse
clientId: loc-studio-frontend

This profile is prepared for [2. Login First](https://hackmd.io/1hD9e4pzQLS1u7XVx9b_mw?view#2-Login-First) to make LOC API request.

:::info
How to add these 3 keys into profile (Below is **MacOS** installation step for your reference):

- Step 1. Replace the old execution file with the v0.5.0 one
- Step 2. In the terminal, change the access permissions of the file system objects

chmod a+x ./loc

- Step 3. Check the profile list first.

loc profile get

You might see these 3 keys are not there.
- Step 4. Add these 3 keys into the profile.

loc profile set [options] [key] [value] 

After adding these 3 keys, you will get something like this when checking again the profile.

{
baseURL: 'https://api.loc-cse.fst.network',
namespace: 'saffron-pd-cse',
realm: 'loc-cse',
clientId: 'loc-studio-frontend',
authURL: 'https://auth.us-west-2.fst.network/auth'
}
:::

## 2. Login First

We should use access token to make our API requests authorized. Use `loc login` to get access token from LOC server and put access token in profile.

loc login
? Username: <Your username>
? Password: <Your password>

Please contact our members to get your credential info (username, password).

## 3. Data Process Configuration

New default:

version: 0.1.0
name: test2
description: description
timeoutSeconds: 180
aggregatorLogic:
  name: aggregator
  file: aggregator-logic.ts
genericLogics:
  - name: generic-1
    file: 1.ts
  - name: generic-2
    file: 2.ts

We should notice that `digitalIdentity` has been removed. And now we should set the resource `name` for future recognition.

And we have one new field `timeoutSeconds` to control data process timeout limit.

## 4. API Configuration

New default:

method: GET
mode: Sync
encapsulation: true
name: this-is-an-example
path: /this/is/an/example/path
dataProcessPids:
  - pid: 00000000-0000-0000-0000-000000000000
    revision: latest

For `0.3.x` version, we have two ways to setup dataprocess binding with apiroute (Because we have `id` and `digitalIdentity` to identify the resource). But in `0.5.x` version, we only have `permanentIdentity` with `revision` as unique contraint. So we should give a dataprocess permanentIdentity and its revision to assign dataprocess for api route config.

## 5. Deploy data process with apiroute

You can deploy dataprocess with apiroute by command below:

loc deploy <template_name> --api-route-config [api_route_config_file]
# or alias `-ar`
loc deploy <template_name> -ar

It will ignore `dataProcessPids` in apiroute config. And set newly created dataprocess' pid as apiroute trigger target.

If we do not give file path for `--api-route-config`, it will read `api-route-config.yaml` as default config file (which is `loc new` default).

## 6. Alias

We can use alias to to access LOC resource now. Such like:

loc l
loc dp
loc ar

`l` is for `logic`, `dp` is for `dataprocess`, and `ar` is for `apiroute`.

## 7. Permanent Identity

The breaking change from `0.3.x` to `0.5.x` is that we remove `digitalIdentity` and add `permanentIdentity`, especially for `logic` and `dataprocess` (`apiroute` is still use `id` as its primary key, but it is also digitalIdentity-removed).

The permanent identity is generated dynamically when resource is created. So we CANNOT predefine this one in our config (IMPORTANT!). So we should setup apiroute `dataprocessPids` after dataprocesses created. Or you should choose `## 5. Deploy data process with apiroute` to deploy all resources in one step.

## 8. Database Agent Interface

javascript example:

const connectionInfo = {
  host: process.env.dbServer,
  port: process.env.port,
  username: process.env.username,
  password: process.env.password,
  database: process.env.database,
};

let db = await ctx.agents.database?.connect({
  // "MSSQL", "MySQL", "Postgres"
  databaseDriver: "MSSQL",
  // "MssqlParameters", "MySqlParameters", "PostgresParameters"
  // MssqlParameters needs `trustCert` field.
  connection: new Saffron.Database.MssqlParameters({
    ...connectionInfo,
    trustCert: true,
  }),
});

let resp = await db?.query(
  "SELECT TOP 2 * FROM dbo.FINB00 WHERE B00_SEQ_NO = @P1;",
  ["EIS36840630"]
);
if (resp !== undefined) {
  await ctx.agents.sessionStorage.putJson("query_resp_rows", {
    resp: resp?.rows,
  });
}

await db?.disconnect();