Test page builder

Summary

This video tutorial provides an introduction to Configurable Web Services (CWS) and basic actions within Page Builder. CWS is a server-side feature in Mocha that allows developers to expose commands as web services without writing new code. The video explains key concepts like actions, resources, and CRUD operations (Create, Read, Update, Delete), using XML files to configure them. It also covers how CWS manages data types, primary keys, and HTTP requests through action arguments, authorization settings, and web service configurations. Overall, the tutorial equips users to manage CWS and its configurations effectively.

Takeaways

• 🔧 CWS (Configurable Web Services) is the server-side backend of the Page Builder tool, allowing users to expose Mocha commands as web services without writing new code.
• 📁 CWS is configured through two fundamental elements: actions and resources, both represented as XML files located in a product’s data/WS directory.
• 🔗 Resources model real-world objects with a unique primary key or compound primary key, defining properties and actions to interact with these objects.
• 📜 Properties in a resource correspond to database columns and are essential for configuring Page Builder, defining namespaces for modifying data.
• ⚙️ Actions define specific tasks related to resources, such as adding, listing, editing, or deleting items. These actions are also defined in the XML configuration files.
• 🌐 Each action includes an HTTP method and a URL endpoint, allowing external clients to trigger Mocha commands via web services.
• 🏗️ The command element within an action links the action to a specific Mocha command, which must be pre-defined and cannot be a freeform command.
• 🔑 Arguments can be passed to actions, specifying which data to use, with detailed configurations for each argument's name, type, and location (path, query, header, or body).
• 🛡️ Authorization for actions can be configured, with the highest level of security being 'mocha-admin' and lower permissions as needed.
• 🔄 CRUD (Create, Read, Update, Delete) operations are core actions associated with resources, and these operations can be configured for primary or compound primary keys.

Q & A

What is CWS in the context of this tutorial?

CWS stands for Configurable Web Services and is the backend server-side portion of the Page Builder. It is a feature built into Mocha that allows developers and users to expose Mocha commands as web services without having to write and compile new code.

What are the two fundamental terms that are essential for configuring CWS?

The two fundamental terms essential for configuring CWS are 'action' and 'resource.' An action represents the work carried out by the user (similar to a web service), and a resource is an entity that models a real-world object, usually represented by a primary or compound primary key.

What file formats are used to configure CWS actions and resources?

CWS actions and resources are configured using XML files. These files are located in a product's data/WS directory and are scanned by the Mocha server during startup to build configurable web services.

What does CRUD stand for, and how is it related to CWS?

CRUD stands for Create, Read, Update, and Delete. It represents the basic actions that can be performed on a resource within CWS, allowing users to manage and manipulate data associated with that resource.

Why is the 'properties' element important in CWS configuration?

The 'properties' element is important because it serves as a container for the properties or fields that define the resource. These properties correspond to the columns returned by the Mocha commands used by the resource's actions. It also plays a crucial role in defining the namespaces used by Page Builder when configuring pages and modifying data.

What is the significance of the 'type' and 'ref' attributes in an action element?

The 'type' attribute specifies the type of action being performed (e.g., add, list, get, edit, delete), while the 'ref' attribute is a reference to the ID of the action that is being used for that resource. The 'ref' attribute is required for any action and must match the action's ID.

What is the role of the 'impl' element in CWS configuration?

The 'impl' element stands for 'implementation' and specifies the functionality of the action. It contains the core definition of a configurable web service action, including the Mocha command to be executed and any arguments that should be supplied to the action.

How are arguments defined in a CWS action, and what attributes are required?

Arguments are defined within the 'arguments' element of a CWS action. Each argument requires a 'name' (unique identifier), 'type' (e.g., date, integer, double, float, string), and 'required' (Boolean indicating whether the argument is mandatory). There is also an optional 'description' and 'location' (e.g., path, query, header, or body) to indicate where the argument will be placed in the HTTP request.

What is the default HTTP method for actions defined in CWS, and how is it specified?

The HTTP method for a CWS action is specified within the 'method' element of the action's configuration. It defines how the action will be called (e.g., GET, POST, PUT, DELETE). There is no default method, so it must be explicitly defined for each action.

How does the concept of primary actions work in CWS, and why is it important?

Primary actions in CWS indicate the main CRUD action for a particular resource type. There can only be one primary action of each type (e.g., add, edit, delete) per resource. These primary actions are essential as they are guaranteed to work when manipulating the resource, ensuring consistency and reliability.

Outlines

00:00

📚 Introduction to CWS and Page Builder Basics

The video begins with an introduction to CWS (Configurable Web Services) as the server-side component of the page builder in Mocha. CWS allows developers and users to expose Mocha commands as web services without writing new code. It highlights two key elements: **Actions** (web service operations) and **Resources** (entities that model real-world objects with a primary key). The discussion emphasizes that actions and resources are configured via XML files in the product's data/WS directory, which are scanned during server startup. These configurations are critical in defining how CWS operates within Mocha.

05:01

📝 Understanding Resources and Properties

This section focuses on the definition of **Resources** and their properties within CWS. A resource is identified by a unique ID, which is mandatory, while other fields like **Name** and **Description** are recommended but optional. The resource's properties must correspond to the columns returned by Mocha commands, and they play a crucial role in CWS configurations when working with Page Builder. It is emphasized that each property has a **Name**, and can include attributes like **Alias**, **Primary Key (PK)**, and **Type**, which defines its data type (string, integer, etc.). Proper configuration of these properties is essential for ensuring smooth interactions with web services.

10:03

🔧 Configuring Actions and Web Services in CWS

The focus shifts to configuring **Actions** for resources in CWS. Each action is defined by an ID and is mapped to a specific resource using the **Ref** attribute. Actions include various types like **Add**, **List**, **Get**, **Edit**, and **Delete**, each representing different CRUD operations. The configuration also involves specifying an HTTP method and endpoint for the action. Additionally, the **Impl** (Implementation) section is explained, detailing how actions are linked to Mocha commands in the form of **Arguments**, with a clear explanation of how these arguments are named, typed, and positioned in the HTTP request. This section introduces essential action elements for editing order data.

🚀 Advanced Configuration of Action Arguments and Security

This section elaborates on the **Action** and **Argument** configurations, explaining in detail how each argument must have a unique name and data type (such as string, integer, etc.). It also touches on the **Required** flag for arguments and explains how these are passed in the HTTP request using different locations such as **Path**, **Query**, **Header**, or **Body**. The **Authorization (Auth)** element is introduced, ensuring secure access to actions, typically defaulting to high-level permissions like **Mocha Admin**. The section concludes by discussing the **Primary** flag for actions, which ensures certain CRUD actions have guaranteed functionality for manipulating resources.

🔗 Path, Query, Header, and Body: Specifying Argument Locations

This part explains the different ways to specify argument locations within the HTTP request, including **Path**, **Query**, **Header**, and **Body**. It demonstrates how primary keys and compound keys are arranged and passed in the URL path and query strings. Compound keys are separated by special characters like `*` and `!` and are ordered alphabetically by argument name. The section highlights best practices for specifying these keys and discusses using JSON format for **Header** and **Body** locations when working with HTTP methods like **POST** and **PUT**.

Keywords

💡CWS (Configurable Web Services)

CWS refers to the server-side component of the Page Builder tool used in Mocha, enabling developers to expose Mocha commands as web services without writing new code. This feature simplifies integration by offering pre-defined services, which are configured through action and resource files. It is foundational to the video as the tutorial explains its usage and configuration in creating CRUD operations for web resources.

💡Mocha

Mocha is the platform where CWS is implemented, serving as the backend server that processes commands and resources. Within the video, Mocha is mentioned as the system where web services are built and deployed through the use of predefined actions and resources. Understanding Mocha’s role is key to understanding how CWS operates in a real-world application.

💡Action

An action in CWS defines the work or task a web service performs, such as creating, reading, updating, or deleting a resource. In the script, it is associated with CRUD operations, mapping to a resource to perform specific functions. Actions are represented as XML files and must be referenced correctly within the resource configuration to execute tasks properly.

💡Resource

A resource in CWS is an entity that models a real-world object, defined by a unique identifier (primary key) and associated with actions. It typically holds a list of properties and serves as the data model for the actions to work upon. In the video, resources are used in CRUD actions, and their properties are defined in XML format, dictating how data is managed.

💡CRUD (Create, Read, Update, Delete)

CRUD refers to the four basic operations performed on resources through web services: create, read, update, and delete. These operations are fundamental to managing data within CWS. The script focuses on configuring these actions, showing how resources are manipulated through CRUD operations and discussing the primary actions associated with each type.

💡Primary Key

A primary key (PK) is a unique identifier for a resource, essential for distinguishing between different instances of that resource. In CWS, PKs are required for creating, updating, or deleting specific resources, and they must be correctly defined in the resource configuration. The video highlights the importance of specifying primary keys, especially in compound keys where multiple elements are used.

💡XML

XML (Extensible Markup Language) is the format used to define both resources and actions in CWS. It allows for the structured representation of data models and configurations. The video frequently references XML files, showing how resource and action elements are organized and how Mocha uses these files to configure web services upon server startup.

💡HTTP Method

The HTTP method specifies the type of operation a web service performs, such as GET, POST, PUT, or DELETE. In the context of the video, HTTP methods are used to call web services, with each action specifying which method to use (e.g., POST for creating data or GET for retrieving data). These methods are part of the web service configuration in CWS.

💡Command

A command in CWS refers to the actual functionality that a web service performs, as defined in Mocha. The command is linked to an action and specified in the configuration using a concrete Mocha command. Commands are the core logic behind web services, and in the video, they are tied to the resource actions, allowing CRUD operations to be executed.

💡Arguments

Arguments in CWS are the parameters passed to an action to execute a specific command. These can include primary keys, resource properties, or other required data, and they are defined in the XML configuration of an action. The video explains how arguments are critical for CRUD actions, specifying how they should be passed in the HTTP request and where (e.g., query, header, body).

Highlights

CWS (Configurable Web Services) allows developers to expose Mocha commands as web services without the need for new code compilation.

CWS is the backend, server-side portion of the Page Builder feature in Mocha.

CWS uses two main file types: action and resource files, both in XML format, for configuration.

Resources represent real-world entities with properties and actions, often using a primary key to identify them.

Actions are defined as the work that users perform and are synonymous with web services.

A one-to-many mapping typically exists between resources and actions, which are defined in XML files.

Resource and action configurations are scanned on server startup to build configurable web services for each product.

CRUD actions (Create, Read, Update, Delete) are frequently used with resources in CWS.

Each resource property must have a unique name and can be defined as a primary key or not.

Actions for resources can be of different types such as add, list, get, edit, or delete.

HTTP methods like GET, POST, PUT, and DELETE are associated with specific action configurations.

Arguments for actions need to be defined with names, types, and whether they are required.

Authorization settings for actions default to the highest level (Mocha Admin) unless specified otherwise.

Primary CRUD actions are guaranteed to manipulate the resource properly when performing operations.

For actions involving multiple primary keys, the keys are passed in alphabetical order as part of the HTTP request path.

Transcripts

and welcome to the first section of the

page builder and CWS video tutorial in

this section we'll be covering an

introduction to CWS and basic quote

actions

what is CWS

CWS is the backend server-side portion

of page builder called configurable web

services

this is a feature built into mocha that

allows for developers and users of the

product to expose mocha commands as web

services without having to write and

compile new code

in order to understand basic CWS one

needs to know the two fundamental terms

that are used to configure it there are

also two main file types used to

configure CWS

first element action represents the work

that is carried out by the user and is

synonymous with web service actions are

tied to resources

for resource it's an entity that models

a real world object represented with a

primary key or compound primary key

a resource will usually maintain a list

of properties and actions which enables

a user to work with that type of

resource now normally what we'll see is

a one-to-many mapping of the resource to

actions which we'll see in our example

now both actions and resources are

represented as files in an XML format

that exists in a product's data slash WS

directory I'm server startup the mocha

server scans this directory for each

product defined in its registry

configuration server dot product dears

build configurable web services from the

action and resource files present in

those directory directories those would

be dot action and Dot resources

now I do however recommend that you work

in the laser or EMD directory for this

tutorial if you're following along

let's take a look at the resource that

we have defined for this example

so this is a resource that we're going

to be using for crud actions and credit

stands for create read update and delete

so the first element ID is the unique

identified as a resource it must be

unique and is required for any

configuration

name and description

are self-explanatory they aren't

required Fields but it's uh recommended

that you fill them out if you're working

with other people

properties is a container for the

properties or fields that Define the

resource it should correspond to the

columns that are returned by the mocha

commands this resources actions are

using

so the properties element

um

in the CWS sign it's more of

documentation but it's critical that you

fill this out if you're using CWS as

page builder because this actually

defines what namespaces paid filter is

going to be using uh when configuring uh

pages and modifying data and so on and

so forth so the first element of

property is name each property has a

name which is required for that property

and must be unique for the given

resource an alieness is an alternative

name for the resource it's not required

PK is a Boolean value that indicates

whether this property is a primary key

of the resource

if you do specify that it's a primary

key of the resource you will have to use

that if you're getting an individual

element editing editing it or deleting

data

and type is the data type of the

property it can be a string integer

Boolean double date object or array

value it will default to string if you

leave it undefined description again is

self-explanatory not required

so those are the properties

um values that configure are configured

and the next element is the actions

element so this defines the actions that

are associated with this resource so for

each individual action element you're

going to see a type and a ref the type

is required for any action and it must

be one of the following values add which

creates an element list which returns a

list of elements get which returns a

signal element edit which edits data the

links which removes it match which we'll

cover later and action which performs

some alternative action so in this case

we don't have it defined but it could be

something like ship order that doesn't

necessarily create the updated delete

data but does something with it

and then you'll see the rest which is a

reference to a

an action

uh it's required for any action and this

must match the ID of the action that

you're going to use for that resource

so let's jump into actions and how those

are configured

uh this is the action we'll be using to

edit order data

so here

um you'll see the ID which is the first

element this is the unique identifier

for the action it is required and again

I'm going to specify for a stress that

you need to match the ref tag in the

resource with the idea of the action

that you're using for that resource name

and description it's the same for me as

resource

not necessary but

um encouraging fill it out

and type this relates to the type

element referenced in the resource

action configuration so here if it isn't

defined and will always default to

action

and you can see here it's added

WMS this is a web service config this is

a web service definition of the action

and is acquainted to define the elements

within it method this will be the HTTP

method that is used to call this web

service and ahref this is the URL

endpoint that HTTP clients will call to

execute the multi command

okay now let's move on to inpl stands

for the functionality implementation of

the faction it is important for any

action

and you'll see command

this is the core of a configurable web

service

at least we're in action it is reported

and needs to be a concrete multi command

that is defined in a DOT ncmd file and

it can't be freeform local syntax just a

one-off command so it can't be uh for

example a raw simple block or a groovy

script or anything like that it has to

be just a concrete vocal command

and arguments here's what we can figure

uh which arguments if any should be

supplied to the action

so here you see we have three arguments

Each of which are primary key for this

resource

and in the argument element

the skills that we require are named

and type so name is just a unique

identifier Let's uh the value that's

going to be passed to the resource

and then type which is required can be a

date integer double float

uh string beam array or object

and there's a required

um setting which is a Boolean play for

whether or not this is required

description it's just a description of

the argument and location of the

argument

uh some location

[Music]

um

defines where the argument will be put

in the HTTP request so it can be passed

query header or body

so query is going to be the default here

and as you can see I specify it for all

of these primary keys to from your

location via the path

and when you go over to actually

performing our credit actions I'll show

you how you can with primary compound

keys in the past

so the next element is off

you know this is the authorization

configuration and it will default to

move that to opt mocha admin which is

the highest level security that we have

and up is the low permission required to

call the web service and if you uh

Define it believe it's blank it'll

default.open

and then the next element is primary and

this indicates whether or not this is a

primary crud action that is the only one

primary action of that type per resource

primary actions are guaranteed to work

when using them to manipulate these

particular resources

firstly some resources may have

unrelated credit actions on them which

are actually working with different

resource types and those are not quite

accents for the parent resource and

missile defaults are false

so there are other Market Advanced

configuration options but let's stick

with these for now is we only need to

perform our basic Corrections

so let's cover action argument locations

since this can be fairly confusing what

I mean by this is the actual location

setting on the argument Peg

and this can either be path query header

or body

the path you're going to see an hrf

looking something like this with orders

and then the identifier of the required

and additional arguments specified in

this curly braces

so this can technically be anything

that's recommended that for common

problem primary keys or regular primary

because you just specify it as PK as

you'll notice in the following demos I

learned some of my actions with ordnum

specified in the curly braces well

technically not incorrect this is

considered bad practice so keep in mind

that when you do create your own actions

if you're using compound primary keys to

specify this as PK

now when we look at the URL for

something like this if we're using a

single primary key

this is going to be off of the endpoint

specified in the ahref followed by the

primary key for a compound primary case

a little bit different

so you're going to have the elements of

the compound primary key each one

separated by a star and an exclamation

point

the way that the order of these of these

primary Keys is part of the compound

primary key

or also known as the resource ID

is going to be in the alphabetical order

of the argument name

so when you specify this since client ID

comes before order number an order

number comes before Warehouse ID that's

the order that we would specify here

when I talk about arranging these

arguments alphabetically I don't I'm not

talking about the actual content in the

path of the URL so for example if this

was a it would still be in the same

location because the argument name

Warehouse ID comes last alphabetically

for query the idea prep is going to just

um be an end point and then we're going

to be specifying the arguments in an

HTTP query

so that would look something like this

where you'd have a question mark and

then ID equals something it's just

arbitrary data if you have additional

arguments you would separate them by an

ampersand and then follow suit with the

argument equals something or something

like that

and then for header and body specified

argument locations

typically used for post and put HTTP

methods you would specify that in a Json

as Json data and the header or body of

the request

and Postman and other HTTP clients

actually have utilities of making this a

little bit more usable just keep in mind

to specify this in a Json format since

that's the agreed upon 4.4 of CWS