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

# Quick Start
The quick start section will show you how to create your first data process in LOC Studio. This data process is extremely simple, which will consume a JSON data as data source and emit an event.

Plus, through this quick start, we expect to showcase how effortless to create a data process on LOC Studio and what an event can do - storing important reference value for future use.

## Create a User Account

### Step 1: Create a New User
In order to use LOC Studio, you need a user account.

Logging in with the *User Management* account (provided by FST Network), on the menu of `Users`, click `Add user` to create a new account:


### Step 2: Fill in User Information

`Username` and `Email` are required:



> We strongly recommend filling user information as detailed as possible.

### Step 3: Set a Temporary Password
In the `Credentials` tab, make sure `Temporary` is switched on in order to set a temporary password for the user:


LOC Studio informs the user to change the password upon first login.

### Step 4: Reset the Temporary Password
If `Temporary` is switched on, the user will be asked to change the temporary password after logging in for the first time:



> LOC Studio will automatically log out the current user after **5 mins** of inactivity.

## Create a "Greeting" Data Process
Now after logging in with your new user account, we are going to show you how to create this simple data process as below:

1. User sends a HTTP request to the data process with a JSON payload, which contains a name and an age.
2. The data process emits an event containing a greeting message with user data.


This data process has only one generic logic with one aggregator logic and will emit one event. After creating and deploying the data process, you will be able to see its action in LOC Studio.

### Step 1: Create Project/Scenario/Data Process
In order to create a data process, you need to create a **project** and a **scenario** first.

- Create a project
Under Default Unit, you can either right click that unit or click on the top right to create a new project, with the project name of "Quick Start Project".


- create a scenario
Under Quick Start Project, you can either right click that project or click on the top right to create a new scenario, with the scenario name of "Quick Start Scenario".


- Create a data process
Under Quick Start Scenario, you can either right click that scenario or click on the top right to create a new data process, with the data process name of "Quick Start" and the default timeout of 180 seconds.

:::info
You can freely put a tag onto each data process so that in the future, it will be easier for you to look it up.
:::


Detailed instructions can be found [HERE](https://hackmd.io/HeIFfxw5SquerGr8mcWtKQ?view#Data-Process-Explorer).

### Step 2: Create Logics
As soon as setting up the process explorer in the previous step, you can now create logics for this data process:


:::info
1. We name the data process `Quick Start` for the following demonstration and leave the timeout to the default of 180 seconds.
2. Every data process **must have** one aggregator logic and **at least one** generic logic.
3. You can also put a tag to each logic so that in the future, it will be easier for you to look it up.
:::

Just like what we have mentioned earlier, this data process has one generic logic and one aggregator logic. Each logic has two parts:

- ```if OK``` function (main logic)
- ```iF Error``` function (error handling)

If something goes wrong in ```run()```, LOC Studio will run ```handleError()``` instead. We will not do anything other than print out some error messages. After all, it is always ideal to have the error-handling aspect covered in LOC Studio and you will know where to fix the bugs.

Now let's start coding!

#### Generic Logic Code

In the editing window, click ```Logic Body```. You will find ```if OK``` and ```iF Error``` tabs:


:::info
We will not use ```Potential Labeling``` here - it will automatically detect events in your code *if* you use the event structure that it recognises.
:::

These tabs are corresponding to the main logics and error handling functions we have mentioned above. Copy and paste the following codes:

++**Generic logic - <span style="color:green">[if OK]</span> block**++

For now, the main supported language in LOC Studio is **JavaScript**. The ```if OK``` codes have to be declared as an asynchronous ```run(ctx)``` function (```ctx``` is a context object provided by LOC):

/**
*
*  The codes in 'run' are executed when no error occurrs in Generic Logic.
*
*/
async function run(ctx) {
  
  // a function that transforms byte array to string
  const UTF8ArrToStr = (aBytes) => {
    let utf8decoder = new TextDecoder();
    return utf8decoder.decode(new Uint8Array(aBytes));
  }

  // read and parse JSON data from the request body
  const payload = JSON.parse(UTF8ArrToStr(ctx.payload.http.body));

  // emit an event to event store
  await ctx.agents.eventStore.emit([
    {
      sourceDID: "LOC_Studio",  // source DID
      targetDID: payload.name,  // target DID will be user's name
      labelName: `Hello, how are you, ${payload.name}?`,  // event label (greeting message)
      meta: `${payload.age}`,  // include user's age in the meta field
      type: "default",  // default group
    },
  ]);
}

For example, if the user sends the following JSON data

{
    "name": "Arthur",
    "age": 42
}

This logic would send the following event:

sourceDID: "LOC_Studio"
targetDID: "Arthur"
labelName: "Hello, how are you, Arthur?"
meta: 42
type: "default"

You might also notice that we use ```ctx.agents.eventStore.emit``` to send an event (which will be stored in the event store with user's name and age from the JSON payload). ```ctx.agents``` are the [agents](https://hackmd.io/mwTxDdBjSuiKrAmainQZAA#Data-Process) mentioned in Concepts. They are built-ins so you don't need to worry about importing them from libraries.

++**Generic logic - <span style="color:red">[if Error]</span> block**++

The ```if Error``` is another function declared as ```handleError(ctx, error)```:

/**
*
*  The codes in 'handleError' is executed when an error occurrs in Generic Logic,
*  or the CURRENT running Logic just gets an error.
*
*/
async function handleError(ctx, error) {
    ctx.agents.logging.error(error.message);  // log the error
}

### Aggregator Logic Code
A data process *must* have one aggregator logic which is pretty much the same as any generic logics, except that an aggregator logic cannot emit/retrieve events. The aggregator logic is used to return the final result (usually also JSON data) after the data process is executed.


++**Aggregator logic - <span style="color:green">[if OK]</span> block**++

It is the same as the generic logic with the main function of a ```run(ctx)```:

/**
*
*  The codes in 'run' are executed when no error occurrs in Aggregator Logic.
*
*/
async function run(ctx) {
    ctx.agents.result.finalize({
    status: "ok",
    taskId: ctx.task.taskId,
  });
}

This time we use agent ```ctx.agents.result.finalize``` to send back a JavaScript object (which will be converted into JSON string). The result will be like this:

{
    "status": "ok",
    "taskId": [some task id]
}

We will see an actual response later. Please note that we are *NOT* sending a standard HTTP response - the fields of the JSON response can be customised as whatever you like, and all you need is to design your desired response in the aggregator logic.

++**Aggregator logic - <span style="color:red">[if Error]</span> block**++

The error handling codes for the aggregator logic are the same as before (log the error):

/**
*
*  The codes in 'handleError' are executed when an error occurrs in Generic Logic,
*  or the CURRENT running Logic just gets an error.
*
*/
async function handleError(ctx, error) {
    ctx.agents.logging.error(error.message);  // log the error
}

### Step 3: Deploy the Data Processes
We have finished creating the data process in [Step 2](####Step-2:-Create-Logics). Now we can deploy it.

Right click on the data process and select `Deploy Data Process`. This will initiate the deployment process.


If the deployment is done successfully, you can expect there will be a pop-up window on the bottom right like this:

### Step 4: Testing the Data Process
A data process can be triggered, normally via an API route. However, LOC Studio allows you to invoke it directly for testing. This is also called a *single data process execution*.

:::info
In [Step 5](###Step-5-Invoke-the-Data-Processes-via-an-API-Route) we will see how to deploy an API route on an API platform as well.
:::

After the data process is deployed, right click it again and select `Execute Data Process`.


The screen would then ask you to upload a payload. What you need to do is to create a ```payload.json``` on your computer with the following content:

++**payload.json**++

{
    "name": "Ian",
    "age": 30
}

Make sure the JSON data contains ```name``` and ```age``` fields so that the data process can respond properly. You can change *Ian* and *30* into another name or age you prefer.

Upload your payload file and click ```Execute```:


If you see something like the result below, the data process is executed successfully:


When clicking the ```JSON``` button with an eye icon, you'll find the JSON response same as what you have designed in the aggregator logic:

{
    "status": "ok",
    "taskId": {
        "executionId": "YnHhUUoj4VhHIGj3ga_7Iw",
        "id": "rI8U8XLPpN8psMoq1d_INA"
    }
}

### Step 5: Invoke the Data Processes via an API Route

#### Create an API Route
What we did in [Step 4](###Step-4-Testing-the-Data-Process) was just a quick test. To trigger the data process properly, we need an API route so that we (or any codes) can send HTTP requests to it.

:::info
One major difference between the single data process execution and API routes is that an API route can trigger *multiple* data processes.

Also please note that only the deployed data processes can be linked to API routes.
:::

Firstly, go to the ```API Route``` tab, create an API route folder, and then click ```Create API Route``` on the upper right corner:


We set our API route as follows:

- API Route Name: ```Quickstart```
- HTTP Method: ```POST```
- HTTP Path: ```/YH/Quickstart```
- Request Mode: ```Sync```
- Response Content Type: ```JSON```
- Linked Data Processes: Add the data process ```Quick Start```

:::info
The actual API path would be something like ```https://api.loc.xxx/YH/Quickstart```.
:::

Afterwards, click ```Create```.


#### Test the Data Process with an API Route

You can use an API client tool such as **[Postman](https://www.postman.com/)** or **[Insomnia](https://insomnia.rest/)** to request URL.

We will use the same payload in [Step 4](###Step-4-Testing-the-Data-Process) (but we can simply copy and paste it in the request body this time):

++**payload**++

{
    "name": "Ian",
    "age": 30
}

Select ```POST``` and paste the full API route (including server URL). Afterwards, paste the JSON payload below.

:::info
See:
- ++[Basics of API Testing Using Postman](https://www.geeksforgeeks.org/basics-of-api-testing-using-postman/)++
- ++[Understanding Insomnia REST Client Made Easy 101](https://hevodata.com/learn/insomnia-rest-client/)++
:::

Click ```Send``` and if all go well, you can expect to see the result like this:


You can see the *complete* response from the data process - notice that the response in [Step 4](###Step-4-Testing-the-Data-Process) is actually included under the ```data``` field.

### Step 6: Inspect the Data Process in Data Discovery
Just as we stated earlier, the reason we need events is to store vital reference value for future use. Hence, besides what you can see from the Postman response, there is one more thing you can do with the events - to inspect the *data lineage* through the graphical representation of events.

Click ```Event``` tab under **Data Discovery** and find the event you just sent:

1. copy the ```Execution ID``` of your event. (you may see an execution ID from the Postman response)
2. click ```Add filter``` on top left.
3. select the ```Field``` as ```Execution ID``` and paste your ID in ```Value```.
4. Click ```Save```.
5. Click ```Event``` again, then click the slider bar ```data``` below ```Applied Filters```.


You can see the ```Label Name``` of the event indeed contains the name "Ian" from our JSON payload.

Now let's switch the data discovery window to ```Graph``` mode and it shows the data lineage of the event:


:::info
You can use your mouse scrolling button to zoom in/out and drag the DIDs around.
:::

If you click the event label and then the small menu icon on the right, you can inspect its details. Here you can find the age data ```30``` in the ```meta``` field.

Also:

- *LOC_Studio* is the **source DID**
- *Ian* is the **target DID**
- the arrow "Hello, how are you, Ian?" is this event's **labal name**


:::info
If you send multiple requests to the API route with the same JSON payload, multiple events will appear between the same source and target in Data Discovery.
:::

Congratulations! You have created your first LOC data process and invoke it via an API route. This has already covered many basics in LOC Studio.

---
<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`