[Back to LOC Studio Guidebook](https://hackmd.io/R8uxDVYvQAGhJtqoTWXy6A)

# Reference

- [User Management](#User-Management)
- [Data Process Explorer](#Data-Process-Explorer)
- [API Route Configuration](#API-Route-Configuration)
- [Data Discovery](#Data-Discovery)
- [Agents List](#Agents-List)

## User Management

After clicking `Users` from the left navigation bar, you can select `View all users` to display all users.


In this section, you can not only view all users but also add, edit and delete them.

**Please DO NOT delete any accounts that have been active already, in case their data, such as configured logics or data processes, will be eliminated and affect the operation of the existing accounts. Instead, Please DEACTIVATE them (disable users).**


:::info

Note: Only the Admins have the right to view, create, edit, and delete users.
:::

### Create New Users
- Step 1: Log into LOC Studio User Management with your `Admin account`.
- Step 2: On the left menu, please select `Users`.
- Step 3: On the top right, please click `Add Users`.
- Step 4: Please fill in the user information as detailed as possible. (`Username` and `Email` are mandatory.)


There are a few more steps to be completed.

- Step 5: In the `Credentials` tab, please ensure the `Temporary` button to be switched on to set a temporary password for the user and inform the user to change the password upon login.


Don’t forget this temporary password and remember to give it to the user.

The users are required to reset their password when they login to their account for the first time.


- Step 6: In `Role Mappings` tab, you can check the role authorisation of the selected user.


### Remove Users
- Step 1: Log into LOC Studio User Management with your `Admin account`.
- Step 2: On the left menu, please select `Users`.
- Step 3: Under `Actions`, please select the user you would like to remove and click `Delete`.


### Forgot Passwords
- Step 1: Log into LOC Studio User Management with your `Admin account`.
- Step 2: On the left menu, please select `Users`.
- Step 3: Under `Actions`, please select the user you would like to reset the password and click `Edit`.
- Step 4: Switch to the `Credentials` tab, under which you will find the `Reset Password` section.
- Step 5: After deleting the old password, please ensure the `Temporary` button to be switched on to set a temporary password for the user and inform the user to change the password upon login.
- Step 6: That user ==MUST== reset the password after the first time login.


---

## Data Process Explorer

After logging into LOC Studio, please click the menu of `Data Process` on the left, and, afterwards, select `DP Interactive Map`.


Below, we are going to explain the structure of `DP Interactive Map` and how to start deploying a data process via LOC Studio.

### Unit
A **Unit** is default in LOC Studio at the beginning. You can regard a **Unit** as one business unit such as marketing, sales, operation, etc. Normally speaking, there is only one (business) **Unit** for a user to access.

If you want to know more about the information of a certain **Unit**, please right click **Unit** and select `Unit Info`.


#### Create a Unit
For the time being, it is not supported for users to create a **Unit**. If you need to create one, please contact your Admin or FST Network.

#### Edit a Unit
For the time being, it is not supported for users to edit the **Unit**. If you need to edit one, please contact your Admin or FST Network.

#### Remove a Unit
For the time being, it is not supported for users to remove a **Unit**. If you need to remove one, please contact your Admin or FST Network.

### Project
If you want to know more about the information of a certain **Project**, please right click that **Project** and select `Project Info`.

#### Create a Project
If you would like to create a **Project**, please right click **Unit** and select `New Project`. After filling in the **Project Name** and click **Create**, this project will be created.

In each **Unit**, you can create several projects.


:::info
Please note that
- `Project Name` is required.
- `Description` is optional.
- In each **Unit**, `Project Name` cannot be the same.
:::

#### Edit a Project
If you would like to edit a specific **Project**, please right click that **Project** and select `Project Info`. In the pop-up window, please click `Edit` to start your revision. Once completing the revision, please click `Update` to keep your latest revision; if you would like to give up this revision, please click `Cancel` to exit.


#### Remove a Project
If you would like to remove a specific **Project**, please right click that **Project** and select `Delete Project`.


:::info
Please note that once you `Delete Project`, there is NO WAY to make it back. Please think twice before your action.
:::

### Scenario
If you want to know more about the information of a certain **Scenario**, please right click that **Scenario** and select `Scenario Info`.


#### Create a Scenario
If you would like to create a **Scenario**, please right click **Project** and select `New Scenario`. After filling in the **Scenario Name** and click **Create**, this scenario will be created.

In each **Project**, you can create several scenario.


:::info
Please note that
- `Scenario Name` is required.
- `Description` is optional.
- In each **Project**, `Scenario Name` cannot be the same.
:::

#### Edit a Scenario
If you would like to edit a specific **Scenario**, please right click that **Scenario** and select `Scenario Info`. In the pop-up window, please click `Edit` to start your revision. Once completing the revision, please click `Update` to keep your latest revision; if you would like to give up this revision, please click `Cancel` to exit.


#### Remove a Scenario
If you would like to remove a specific **Scenario**, please right click that **Scenario** and select `Delete Scenario`.


:::info
Please note that once you `Delete Scenario`, there is NO WAY to make it back. Please think twice before your action.
:::

### Data Process
If you want to know more about the information of a certain **Data Process**, please right click that **Data Process** and select `Data Process Info`.

#### Create a Data Process
If you would like to create a **Data Process**, please right click **Scenario** and select `New Data Process`. After filling in the **Data Process Name** and click **Create**, this data process will be created.

In each **Scenario**, you can create several data processes.


:::info
Please note that
- `Data Process Name` is required.
- `Description` is optional.
- `Execution Timeout` is required and defaulted as 180 seconds. If the data process is too complicated with a large amount of data, when executing the data process, it might fail because of the default execution timeout.
- In each **Scenario**, `Data Process Name` cannot be the same.
:::

#### Edit a Data Process
If you would like to edit a specific **Data Process**, please right click that **Data Process** and select `Data Process Info`. In the pop-up window, please click `Edit` to start your revision. Once completing the revision, please click `Update` to keep your latest revision; if you would like to give up this revision, please click `Cancel` to exit.

#### Remove a Data Process
If you would like to remove a specific **Data Process**, please right click that **Data Process** and select `Delete Data Process`.

:::info
Please note that once you `Delete Data Process`, there is NO WAY to make it back. Please think twice before your action.
:::

### Logic
A (generic) logic is the minimum component of a data process which must be composed with ==AT LEAST== `1 (generic) logic` and `1 aggregator logic` on LOC Studio.

#### Create a (Generic) Logic
If you would like to create a **(Generic) Logic**, please click `+Generic Logic` to choose where it suits you and start coding.


In the `Logic Body` tab, you can either write codes yourself or use `+New Potential Labelling`, and the latter is only for creating an event.

As for using `+New Potential Labelling`, you need to firstly right click on where you would like to put in the `Logic Body` and then simply put your `Label Name`, `Meta`, `Source DID`, and `Target DID` into the pop-up window. Please note that only `Meta` optional to be filled in, the rest are required. Additionally, the potential labelling is used to emit an event.

After completing the form, these information will be automatically transformed into codes and shown in the `Logic Body`, where you can revise further.


:::info
Please note that `Label Name`, `Meta`, `Source DID`, and `Target DID` will be treated as string when converting from the potential labelling to the logic body.
:::

#### Create an Aggregator Logic
If you would like to create an **Aggregator Logic**, please click `Add Aggregator Logic` to start coding.

Here are the templates of the aggregator logic for your reference.

- if OK

export async function run(ctx: AggregatorContext) {
    const result = (await ctx.agents.sessionStorage.get("result")) as object;
    ctx.agents.result.finalize({
    returnCode: "000", // or other success codes
    returnMsg: "Success", // or success messages
  });
}

- if ERROR

export async function handleError(ctx: AggregatorContext, error: RailwayError) {
    ctx.agents.logging.error(error.message);
}

:::info
Please note that
- `Logic Name` is required.
- In each **Data Process**, `Logic Name` cannot be the same.
- `Description` and `Comment` are optional.
- `Description` contains general words that apply to all versions of this logic even if this logic is revised.
- `Comment` contains specific words to describe the version of this logic.
- LOC Studio currently supports JavaScript only, but more programming languages will be added, such as TypeScript, etc.
:::

#### Edit a Logic
If you would like to edit a specific **Logic**, please click this icon "⋮" of that **Logic** on the top right and select the edit icon as shown below to start your revision. Once completing the revision, please click `Update` to keep your latest revision; if you would like to give up this revision, please click `Cancel` to exit.


#### Remove a Logic
If you would like to delete a specific **Logic**, please right click that **Logic** and select the rubbish bin icon as shown below.


:::info
Please note that once you `Delete Logic`, there is NO WAY to make it back. Please think twice before your action.
:::

---

## API Route Configuration

After logging into LOC Studio, you can find the menu of **API Route** on the left. Once completing deploying a data process, you can configure an API route to execute it.

:::info
- Please note that only the deployed data processes can be configured here.
- The order of the linked data processes is important and will affect the result.
:::


### Create an API Route
If you would like to create an **API Route**, please click **+** right next to `API Route Explorer` to create a new folder first by filling out the information.

Before creating the folder:

After creating the folder:

:::info
Please note that
- `Folder Name` is required.
- `Description` is optional.
- In each folder, `Folder Name` cannot be the same.
:::

By clicking `Create API Route` on the top right, you will be able to configure an API for a specific data process. We need to stress that only the deployed data processes can be added; otherwise, the undeployed data processes cannot be selected, and hence the API route configuration cannot be completed.


:::info
Please note that

- `API Route Name`, `HTTP Method`, `HTTP Path`, and `Linked Data Process` are required.
- `Description` is optional.
- In `HTTP Path`, you only need to fill in the sub-path; the domain name is default in the system and thus there is no need to put domain name here. (eg, complete HTTP Path might be `https://api.xxx.xxx.xxx/api/v1/search`; here, only `/api/v1/search` is needed to be filled in.)
- `HTTP Path` cannot be the same.
:::

After configuring an API, you will have this success page. By using this API and requesting it on any API platforms (such as Postman, Insomnia, etc), it will return the result as stated in the aggregator logic of your data process.

(Configuring an API route)

(Using Postman to invoke this API route)

### Edit an API Route
If you would like to edit a specific **API Route**, please click that **API Route** on the top right. In the pop-up window, please click `Edit` as shown below to start your revision. Once completing the revision, please click `Update` to keep your latest revision; if you would like to give up this revision, please click `Cancel` to exit.


### Remove an API Route
If you would like to remove a specific **API Route**, please right click that **API Route** and select `Delete API Route`.


:::info
Please note that once you `Delete API Route`, there is NO WAY to make it back. Please think twice before your action.
:::

---

## Data Discovery

### Event
This repository is where users can see the relationship between each `event` or switch to graph for visualisation, helping to fulfil event sourcing.


By clicking **+**, you can see more details of this particular event.


Also, switching to the graph and setting up the filter of your interest allow you to see a clearer relationship of each `event` for event sourcing or BAM.

### Label Name
Every `event` has exactly one `label name` and two `DIDs` (source and target). However, one `label name` can be re-used in different `events`. In this repository, you are able to filter a specific `label name` for all the`DIDs` related to that.


### DID
This repository is where users can see the relationship between the `DID` and the `label name`. You can choose a specific `DID` and see all the `label names` related to it.


### Application of Data Discovery
Whenever an `event` is emitted, 1 `label name` and 2 `DIDs` (source and target) will be created as what you have set up. Additionally, you might have created multiple `events` with the same `label name`, or multiple `DIDs` related to the same `label name`. In this case, each repository has its work to do indeed.

For example, in the graph shown below, there are 4 `events` with 2 different `label names`, 4 `source DIDs`, and 3 `target DIDs`. We can go to [Event](###Event) and search all the `events` in this execution to get this relationship graph. In addition, you may feel interested in how many `DIDs` have been created with a specific `label name`; let's say, labelName_1. After searching this `label name` in the [Label Name](###Label-Name), you will get 3 `DIDs` (2 source and 1 target). On the other hand, you can go to [DID](###DID) to check out how many `label names` have been put onto a specific `DID`; let's say Target_1. In this case, you will see 2 `label names` have been put onto Target_1 in the sense that 2 `events` share the same `target DID` (Target_1).

In conclusion, the feature of [Data Discovery](https://hackmd.io/HeIFfxw5SquerGr8mcWtKQ?view#Data-Discovery) helps our users to quickly inspect the relationship of the `events` and discover some useful information or insights on a certain `event`, `label name`, or `DID`.


## Agents List

See: [Agent List](https://hackmd.io/Uj-tC7l9Q82VyGr8R5PL2Q).

---

<text style="font-size:17pt">**LOC Studio Guidebook Catalogue**</text>

<text style="font-size:13pt"> [Introduction](https://hackmd.io/PtsDJXYvReqsoGo_jR_4KA?view)</text>
<text style="font-size:13pt"> [Concept](https://hackmd.io/mwTxDdBjSuiKrAmainQZAA?view)</text>
<text style="font-size:13pt"> [Quick Start](https://hackmd.io/_BXotO9kSQulpZLHuAOjwA?view)</text>
<text style="font-size:13pt"> [Use Case: Lakeside Oasis Café](https://hackmd.io/JvP9MTvgSmGEubrizwSWVQ?view)</text>
<text style="font-size:13pt"> [Reference](https://hackmd.io/HeIFfxw5SquerGr8mcWtKQ?view)</text>

###### tags: `LOC Studio`