Web-IDE: User Guide

ZOAPIIO Overview

is a one-of-a-kind on-line build-and-host development environment.

's unique Web based Development Environment (Web-IDE) takes the task of building server Web-APIs out of traditional boundaries and puts it in the hands of everyday users. If you have a good understanding of your business requirements, and a basic exposure to XML, JSON and concepts of programming logic, you can build, deploy and use Web-services (or APIs) in . Introductory and refresher public resources on programming concepts and XML/JSON are freely available on the Internet.

has several use cases and can be used in different configurations depending upon the requirements.

  1. Web-API is the most basic use case. Every solution that gets built and run in will use the Web-APIs.
  2. Another prominent use case is the end-to-end Business ERP Applications, which strongly leverages code generation. Application Wizard generates for you, the complete application from a single high-level configuration file.
  3. Finally, you can build full-scale consumer facing Web and Mobile applications, with multi-fold productivity and time-to-market gains.

Unboxing - First look

If you are just getting started and have not already seen this video, we suggest you view it now.

Web-IDE is targeted to non-experts, and this guide is presented with that in mind. If you have prior programming experience, you may skim over some sections.

Introduction to Web-APIs

Hello, World!

A great way to get familiar with a new environment is to learn by example. That is why every introduction to a programming environment starts with a "Hello, World!" example. While we do not have an exact equivalent here, Web-IDE provides built-in sample applications that help you ramp up quickly. We recommend that you use the information presented here with the sample applications and learn by example.

You can sign-up for a free on-line instance on ZOAPIIO.COM and get started right away.

What is Web-API

API stands for "Application Program Interface" and its basic purpose is to allow two modules within an application to interact with each other - like a telephone call does for two individuals. One application initiates the call to another through the API, and data is exchanged. The data exchange could be one-way or two-way. To illustrate using an example, the payroll module of your ERP may need information on the number of days an employee attended office, information that is available with the HR module. A simple API between the two would enable the payroll application to compute each month's payroll without any human intervention.

A Web-API (also known as Web-service) is similar, except that it allows two entirely different applications, possibly owned by two completely different parties, to interact using the Internet as the medium. The data is exchanged both ways and format used to package the exchanged data is usually XML or JSON. As you are probably already guessing right now, security plays an important role in Web-APIs because the medium is a public medium.

Web-APIs have an advantage over conventional APIs in that the communicating applications need not be based on a common technology, environment, or programming language. If each supports the HTTP protocol, they can communicate. This advantage has led to its fast acceptance - architects now prefer to use Web-APIs even to communicate within an application, even though they share the same technology. This keeps the integration open and future-proof. It is also for this reason that the Web-APIs and Web-Services are now simply referred to as the APIs.

Message Format API Request (Client) Response (Provider)
XML <GetTemperature>
    <Country>UK<∕Country>
    <City>London<∕City>
<∕GetTemperature>
<Temperature>
    <Country>UK<∕Country>
    <City>London<∕City>
    <Unit>Centigrade<∕Unit>
    <Temperature>24.5<∕Temperature>
    <DateTime>2019-01-01 11:00:05<∕DateTime>
<∕Temperature>

JSON {
    "Country": "UK",
    "City": "London"
}
{
    "Country": "UK",
    "City": "London",
    "Unit": "Centigrade",
    "Temperature": "24.5",
    "DateTime": "2019-01-01 11:00:05"
}
Web-API illustration for a public (open) weather service.

For request and response messages, the format and content (fields and structure) is fixed and each party knows what to expect and what each field means. XML and JSON formats allow the request/response messages to be human readable and hence easy to understand. If you are a provider of an API, you are free to decide the structure of the message and then share it with the API clients. If you are consuming services provided by others, then you need to know the structure published by them so that you can prepare and interpret the messages accordingly.

Web-IDE needs to know the structure of the messages that will be exchanged with clients and providers. The easiest way to provide these is through a sample JSON or XML file which can be easily obtained from the documentation of the Web-API providers. If you are providing an API, then it is recommended that you prepare a sample XML/JSON file for the request and response. Think of it like a part of your API design - it will give you clarity on what you are trying to build. The other method of providing the message structures to Web-IDE is through an XSD file, which is a standard way of describing hierarchical structures. Some API providers include XSD schema in their documentation.

allows you to use undeclared message structures but this is highly discouraged because it keeps the Web-IDE from validating the message node references in your program. Such situations result in run-time errors which are more difficult to debug.

HTTP Transport

Web-APIs work using the HTTP transport - this means that the same HTTP protocol that you use to browse the web is also used to send and receive information in a Web-API. In fact, some Web-APIs (though not all) can be accessed from the browser itself. A Web-API is a resource on the web, like a webpage. It has an endpoint (or entry point) which is identified by a URL - quite like the URL that you type in your browser to reach a webpage.

Web-APIs will typically be invoked from another application or program - but for the purpose of testing, you will need a mechanism to invoke them from a test environment. Some Web-APIs can be directly called by typing their URL in your favorite browser. For others, you will require a desktop tool which allows greater control on how the APIs are called. A popular tool that lets you do this is 'Postman' - it is recommended that you install this on your desktop because you will need it to test your Web-APIs. Another similar tool is SoapUI, which also supports SOAP - if you plan to build SOAP services, then you should install SoapUI.

HTTP requests most commonly use a GET or a POST method (although other methods are also there) for communication. A GET request can carry information forward only as a part of the URL, which is difficult to read and has size limitations - it is useful when the outgoing message is small and simple. The POST request can carry arbitrary sized data which is sent separately from the URL and is preferred when the outgoing data is large or complex. Both GET and POST can receive data of any size and in any format - typically, HTML, XML or JSON.

MQ Transport

A lesser used but still useful way to communicate over the web is the Message Queue transport. HTTP communication is synchronous - means that the data is exchanged within the same unit of transaction. A message sent using the Message Queue, on the other hand, is not processed immediately but queued for later processing. The Client does not receive the response of the message handling. MQ transport is useful when the communication is mostly one-way, and the traffic is high - implying that the requirement of an immediate response will create a high-load situation on the servers. A class of applications that make heavy use of MQ transport is in the field of IOT. Typically, the number of devices is quite large in the network and each device is mostly engaged in one-way communication of reporting its status to the application.

Transport Seq Client (Requestor) Communication Server (Provider)
HTTP 1 Send Request
2 Process request and reply
3 Receive Response

MQ 1 Send Request
2 Store request and acknowledge
3 Receive Acknowledgment (no response)
4 Process request later
Web-API transport comparison.

SOAP Protocol

SOAP is another protocol for using Web-APIs that is also based on HTTP but has some differences in the way it works. You can look-up the details of the SOAP protocol on the Web if you are interested, but SOAP is losing popularity, and we advise you to use HTTP services for your application. However, it is possible that you may still need to deal with SOAP because a service that you need to consume from another provider uses SOAP protocol.

Web-Socket

Web-Socket is a special purpose communication protocol used in high-traffic situations. A conventional Socket in programming represents a permanent two-way channel between two communication parties. The communication is not transactional, but data is continuously transmitted in both directions. Since the connection is permanent (for the life of the socket), no time is wasted in establishing the connection with every message.

A Web-Socket is an adaptation of Socket functionality over HTTP and provides similar capability that Sockets do. Web-Sockets generally do not figure in business applications and the chances of you requiring them are low. However, allows you to build Web-Socket services.

GraphQL

GraphQL is another convenience construct used in client-server communication over the web. It also uses the HTTP GET/POST as underlying transport mechanism, but the messages have a certain structure that carries operational instructions to the server along with the data. The most common GraphQL feature is the ability to specify the fields that should be returned in the response.

GraphQL is gaining popularity but developing GraphQL server is much more complex than classical HTTP REST APIs. Fortunately, allows you to write GraphQL services with utmost simplicity. It is still an advanced subject, and most projects are based on HTTP/REST services. Should you require GraphQL for your project, ZOAPIIO has full support.

runtime allows you to consume as well as provide Web-services of all types - I.e. HTTP based (GET, PUT, POST etc.), MQ messages, SOAP, GraphQL and Web-Socket. handles the internal mechanism of communication and data formatting. You as the application designer, will concern mostly with your business processing.

ZOAPIIO Programming Model

Your Instance consists of

  1. A runtime, or the application container - this is where your programs are stored and executed, and all the other magic happens. runtime is a Java application running under a Java Web-Server, such as Tomcat.
  2. A web-based development environment consisting of Web-IDE and supporting tools. All the development tools are web-based, which means that you never have to install anything on your desktop or use any third-party services or tools.
    • The WebIDE designer, where you design and develop the apps. Also, all other supporting tools are launched from here. The Application Wizard is a part of the designer.
    • The DB Assistant, from where you can manage your relational databases - like create tables, browse/update data etc.
    • A Debugger - no IDE is complete without a debugger. The services running on the server can be debugged using the web debugger.
    • A trace log viewer. Sometimes, the execution trace log inspection can reveal errors faster than executing under the debugger. You can view the execution trace to spot errors quickly and easily.

Your Programs (server) are-

  1. Composed of Web Services - almost all API types are supported (See the Introduction above).
  2. Written using a high-level abstraction language allowing you to write the business logic without concerning with underlying Java programming constructs.
  3. Parts of your application can be written in Java programming language. This is useful, at times essential, in managing complex computational tasks.
  4. The data schema declares the structures of communication messages, database storage, and transient storage.
  5. The programs are saved in a proprietary format (XML format).
  6. Basic version control is applied to your project file.

The schematic below provides an overview of the components in a ecosystem. The Application container is fully managed and is hosted on the cloud.

Visual representation of the runtime and developer tools.

Abstraction

The proprietary abstraction language (4GL) is very compact and powerful. leverages the power of XML (hierarchical structures) and abstracts all entities in your development environment as XML nodes. This means that you access all elements of your programming environment as if they were a part of one large XML document. For instance, a database table appears as a node in your project Schema - takes the responsibility of mapping the node to the underlying entity, the database table in this case. Same is true of all entities in the system. You, as API developer, do not have to be concerned with technical internals like where the database is located and how the data is retrieved and updated.

The abstraction principle used by , greatly simplifies your programming experience and sharply reduces the learning curve. It is also responsible for a large part of the productivity gains.

Logic Builder

Web-IDE allows you to write your business logic using an intuitive drag-n-drop graphic program builder.

The logic builder is built using Google's blockly - an UI for teaching programming to children. As you use the logic builder, you will notice that little programming knowledge is required to build algorithms.
  1. To add a command, or a data element (expressions, constants and Data paths) select from the menu on the left and then drop it on the program block.
  2. An item (commands, data elements) can be attached to an appropriate point in the program block using its connector.
  3. The Web-IDE will not allow you to connect a selected item where it does not belong.
  4. To remove an item from the program block, simply drag it into the recycle bin (at the bottom right corner).
  5. You can move items in the program block by dragging them out or their present position to a new position.
  6. You can drag an item from the data schema window and attach it at a point that expects a Data path.
  7. You can edit the values inside items, or choose from the provided drop-down, where appropriate.
  8. As you type the Data paths and expressions in the program block, Web-IDE will validate them and flag errors if any.
  9. The right-click on an item in the program block will show you the context menu, from where you can access utility functions like enable/disable, duplicate, etc.

A simple program in Web-IDE.

Schema

Recall your first programming course, where you learnt that a computer program is data+logic - don't worry if you never went to a programming school, you've learnt it now. In most environments, the data elements that your program would use are declared beforehand and a datatype is attributed to it so that computational operations on it can be validated and appropriately handled.

In your data elements are hierarchical structures in direct correspondence with the structure of the Web-API messages which are also hierarchical. The data elements are declared in the Schema - the left panel in your Web-IDE window. As you should expect, much of your schema will be composed of the messages that you exchange with clients and other services. Additionally, you will have some working data structures that are used to store intermediate results and temporary data.

Reusable Structure Declarations

Many messages in a Web-API have the same structure, and it is only natural that they are declared only once and then used multiple times. Otherwise, your schema can become very complex and large - not to mention, a nightmare to maintain. provides the TYPES node in the schema for this purpose. The contents under the TYPES node have the same declarative format, but do not have any storage associated with them. They must be referenced in the Data Schema before they can be used.

It is a recommended practice to declare your message structures under TYPES as a pure declaration, even if they may be used only once.

Data Schema

You will declare data element structures to be used by your Web-APIs directly under the Schema, or you can organize them as sub-nodes under a root level group. This helps keep large projects manageable and easy to read. In , you will declare your working data elements under the VARIABLES node - they can be hierarchical structures just like everything else. Using VARIABLES node to declare your working data is not strictly a requirement most of the time, and you can declare them anywhere. Except when writing the logic for your Web-APIs, some index references are required to be under the VARIABLES node. For clarity, it is recommended to keep your working data separate under VARIABLES.

Your session variables (again, can be hierarchical) are declared under the SESSION node. See Application Session

The Schema will also contain all abstracted entities in the system, which, as explained above, appear as XML nodes. Some of the entities abstracted in are-

Element Description
DATABASE-TABLE A database table with support for DB read/update operations.

DATABASE-QUERY A database query (query and updates) to handle complex database interactions.

MONGO-COLLECTION A MongoDB collection.

SESSION Abstraction for the application session. See Application Session.

REQUEST Abstraction for the HTTP Request. When the Web-API is entered, the caller can pass parameters to it as standalone values or through complex XML/JSON structures. The REQUEST node will allow your Web-API to access the input that was passed to it.

COOKIES Abstraction for the HTTP Cookies. You can access the cookies in the input request and set Cookies in the output using this node.

PROPERTY-SET Abstraction for the application properties. An application typically has some fixed settings, which can be changed from outside without the need to recompile the application. This node provides read-only access to your application properties.

The properties are stored in a database table. You can view and update them using the DB Assistant.

EMAIL-SENDER Abstraction of an SMTP server for sending email messages.

Programming

The data in your project needs to be processed - you provide Web-APIs for this purpose and write the processing logic (or the program) against these. In line with 's abstraction approach, the processing details are also captured as a part of the project Schema. The "Business Flows" node in the schema is used for the purpose of declaring, among other things, the Web-APIs that you provide.

The building of programs, or programming, has traditionally been a complex task meant for experts. To make matters worse, this complexity has grown over time with the introduction of frameworks, such as Spring, as it dramatically raises the entry level skill requirements for your programmers.

As we promised in the beginning, building Web-APIs is not conventional programming. A basic working understanding of programming logic constructs like expressions, conditions, statement blocks, loops and branching, is all that is required.

The algorithm

An algorithm is like a recipe that contains step-by-step instructions on how to start from raw input (ingredients) and arrive at the output (the finished dish). Think of branching and iterations like you would find in a recipe. E.g., "if gas oven, pre-heat for 10 mins, else if electric oven, pre-heat for 20 mins" (condition), or "stir gently until light brown" (iteration).

A Web-API process, or a program, is made up of statements (or commands) in a sequence - called blocks. The system will execute these commands sequentially starting at the top. The execution continues until the last statement is reached, or the program comes across a "conditional statement" or an "iteration" (called control statements)- the control statements change the program flow.

A conditional statement ( If statement) contains a condition and a block of statements. If the condition evaluates to true, the associated block is executed, otherwise the execution continues with the statement following the IF statement. A variant of the basic IF is the multiple branching statement (IF... ELSE IF.... ELSE...), where multiple conditions and multiple blocks are present. Depending on which condition is true, the corresponding block is executed.

In multiple IF statement, maximum one block will be executed, but none might be executed (if no condition was satisfied). Generally, the last sub-IF block in the IF statement is left without a condition, which means that if no other condition was met, the last block would be executed.

An iterative statement ( ForEach and While statements) is also associated with a condition and a block of statements. The given block of statements is executed repeatedly as long as the condition holds true. The condition is evaluated before every iteration. The block associated with the iteration should eventually do something to make the condition become false, otherwise the program will keep on iterating forever (called an infinite loop).

In a program, the conditional and iterative statements can be nested within themselves or each other up to an arbitrary level. This means that statement block associated with each control statement can contain other control statements. Most typical algorithms would require you to use this nesting very frequently.

Tip: There are many ways to write the same algorithm and a good program is one that is compact and easy to understand. It is advised that before you jump into the Web-IDE to start writing the program, spend some time with pen and paper to sort out the logic clearly.

For your programs, under the "Business Flows" node in schema, you declare the following-

Element Description
DECLARATIONS

This is for advanced use only and applicable only when you are embedding Java modules in your project. Most of the time you are better off leaving this alone.

Internally, your project is deployed inside a Java container, and this contains a wrapper declaration of the Java class that will hold your project. If you need to import Java classes or use Java functions that should be available throughout the project, you will declare them here.

Another time you need to edit this is if you want to create background jobs in your project. See Background Jobs.


WEB-SERVICE A Web-API or service (SOAP or REST), that your project will consume. Please note that there are no MQ services, and to send a request to an MQ server, you will use MQ-DESTINATION.

ENTRY-POINT A REST endpoint (HTTP GET, POST etc.) that your project will provide.

ENTRY-POINT-SOAP A SOAP service endpoint that your project will provide.

ENTRY-POINT-JMS Processor for a Message Queue that your project is serving.

ENTRY-POINT-GRAPHQL Processor for a GraphQL service.

ENTRY-POINT-WEBSOCKET Processor for a Web-Socket service.

ENTRY-POINT-EMAIL Processor for automatically polling an Email account and handling messages. Please see Using Java below on discussion on how to gain access to the incoming message.

ENTRY-POINT-PROCLET A Proclet is a construct representing a business process. It is hosted on a URL like an ENTRY-POINT, but it is accessible only internally within your instance. Different projects hosted in the same instance can access the proclets.

ROUTINE Also called subroutine, a routine is a programming construct that lets you build your program by combining smaller, more manageable, and reusable pieces of logic. Before your start writing it, you should analyze your business process (design) and break-up the process into smaller self-contained sub-processes and build them as ROUTINEs.

METHOD An isolated and independent part of processing like the ROUTINE, except it is written using the Java programming language. This is also for advanced use and if you must use a METHOD and do not know Java programming you should take help from someone in your team.

MQ-DESTINATION A Message Queue to which, your project will send messages. The Queue may be attached to a process within your own project, a different project or to a third-party service, external to your instance.

XSLT XML Stylesheet Transformation (XSLT) is a popular programming tool to process XML (hierarchical) structures. Given that abstraction is based on XML, this feature can be useful and is available to advanced users. In a real-life situation, the only time you will need this is if you have an existing XSLT script that you want to reuse in your project.

XML-STUB A hard-coded XML structure in your project. Sometimes you need to initialize a large structure with fixed values - an XML-STUB provides a very fast mechanism to achieve that.

WEB-SCRAPER A node representing an external HTML source (website) for interfacing through scraping. The web-scraping statements in your programs will use this.

Data Paths

In Web-IDE, you will refer to data elements using the Data Paths. Data Path is a powerful abstraction that hides the complex processing details, which a programmer must deal with in a conventional development environment. Depending upon the underlying entity that a schema node is abstracting, will deal with it accordingly. It should be pointed out here for advanced users that the Data Path is syntactically not same as the XPATH, although it is similar.

It is important to note that the schema in the Web-IDE is only a declaration, and not everything in it will contain actual data. When your Web-API executes, the data schema is populated as the processing continues. At the start, the contents of the REQUEST (or the alternative that you have declared with your Web-API definition) is populated from the incoming request. In the case of SOAP service, the input is populated from the SOAP request. The contents of the SESSION are also fetched.

Other parts of the schema will be populated inside your processing logic. You can freely read or change the contents of the data at runtime. Before your Web-API finishes execution, you should - at the very least - put values in the part of the data tree that comprises of the response (defined with the Web-API declaration). takes care of returning the data to the caller in the appropriate format using the right protocol.

Data Paths look like the file pathnames in your Windows (or Linux) OS. In XML the forward slash (/) is used as the path separator and it separates the name of the elements in your schema, quite like your folder path. Starting from the root node (like the root folder in your file system) you can traverse to any node in the XML data tree, by naming the next element name and separating it with the slash.

Similarity with the file pathnames continues as the Data Paths also have an absolute pathname and a relative pathname. Like you have a default (or the current folder) in your file explorer, inside your program there is the concept of a context path. If there is a context path, then you can use a relative Data Path (I.e., not starting with a slash) and start traversal from the context path.

Indexes and Keys

It is permissible and quite common to have multiple instances of an element in the data tree. An example case would be if you are passing a list of, say, Employees all having the same data structure. In schema you will declare such elements with the attribute "Duplicates" checked.

You need a mechanism to individually access such items - offers two methods to address each individual item in the list - Indexes and Keys. The index appears in square brackets [] and immediately follows the element name. E.g., Employee[10] would refer to the 10th Employee node in the tree. Note that the indexes start from 1 (unlike most programming languages, where indexes start at 0) and if no index is provided, it defaults to the first.

Inside the program you can also use a variable for the index. If you have an element declared under VARIABLES (or _LOCALS - See Declare statement) node of type NUMBER, then you can use that as a variable index. When using a variable index its name should be prefixed with a "#". E.g., Employee[#I] refers to the "I"th Employee where I is the value stored in the node /_LOCALS/I or /VARIABLES/I - searched in that order.

The index value zero (0) is used for a specific purpose. It always points to a new element at the end of the existing list of nodes. Be careful, when using the zero index in a path - every time the path is evaluated, a new element would be created.

To use Keys, the element that is a list should be a group Element and at least one of the elements inside it should be declared as a key ('Is Key' attribute should be checked). The key of each Element in the list is formed by taking each key field in it and concatenating them by the bang (!) character. To access an Element by key, you will enclose it in curly braces {} and put it immediately after the Element name. E.g. Employee{M100}, would select the Employee node whose key is the string "M100". You can use variables in Keys, just like you use them in indexes, except the variable need not be a number. E.g., If Employee Id is the key for the Employee Element, Employee{#EID} would select the Employee with Employee Id 'EID', where EID is an Element under /_LOCALS or /VARIABLES - searched in that order.

Attributes

Attributes are a construct used in the XML representation of data but has no equivalent in JSON. Attributes are used to specify additional information about the XML node. E.g., in XML <Employee Type="Full-Time"> Type is an attribute. It is possible to have "Type" as a sub-node of the Employee node, but attributes improve readability. E.g., the same can be achieved using <Employee><Type>Full-Time ...

In you will declare ATTRIBUTES under the TAG nodes, but if you are using JSON formats for your messages, it is better to avoid them. In the Datapath, the attributes are referenced by putting the attribute name in the end separating it from the rest of the path with an "@". E.g Employee@Type.

Web Scraper Elements

abstracts a Web Scraping data source like everything else. The elements appearing on the web page are referenced using data paths. There are some differences, however, in the treatment of Web Scraper elements.

  1. The structure of the HTML content in a scraper is not declared in advance - it is not possible to know up front the contents of the web source.
  2. In data paths for web elements, the separator (/) is interpreted differently. Normally, the sub-path must be present directly under the parent. But in case of web elements, the sub-path can appear anywhere under the tree below the parent node.
  3. The index for a web element can use attribute selection (See below).
  4. The web elements can have a second index, which acts as the index described above.

The attribute selection in Web element data paths serves to identify nodes in the HTML page by their attributes. The syntax of the index is-

{TagName}[@{AttributeName}:{AttribtueValue}]
Path Description
/ The Root node of runtime data tree.

/REQUEST/EmployeeId The node by name EmployeeId under the REQUEST node under root. Because abstracts the REQUEST node to represent the Web-API HTTP Request (unless specified differently with Entry Point declaration), this would contain the value of parameter "EmployeeId" passed with the request, such as http://...../?EmployeeId=100.

/Response/Employee[20] If multiple Employee nodes are present under the Response node, this path identifies the 20th Employee node.

/Response/Employee[0] This will create a new Employee node at the end of existing Employee nodes under /Response and point to that.

/Response/Employee[20]@Type The Type attribute of the 20th Employee under the Response node under root.

Employee[20]@Type A relative pathname having the same effect as above, if /Response is the context path.

/Response/Employee[#I] Another way to identify elements from an array (multiple occurrences). The value stored in /VARIABLES/I is used as the index value.

/Response/Employee{100} If Employee structure is declared with a key field for EmployeeId, then this would refer to the Employee Id 100.

/Response/Employee{#EMPID} Same as above but with a dynamic key value (/_LOCALS/EMPID or /VARIABLES/EMPID).

/GGL/div[@id:elementid] Assuming GGL is a WEB-SCRAPER, this data path will point to the first div element in the page with id=elementid.

/GGL/div[@class::elementclass][3] Assuming GGL is a WEB-SCRAPER, this data path will point to the third div element in the page with class value containing elementclass. Generally the class specification contains multiple names, so double colon (::) is used for 'contains' match.

/GGL/span[@text::Hello] Assuming GGL is a WEB-SCRAPER, this data path will point to the first span element having 'Hello' anywhere in its text.
Examples of Data Paths used in .

Expressions

In , Expressions are used for manipulating the values in the data tree. This means that for almost everything that you need to do in the program, you will be needing an expression. Thankfully, expressions are simple, and you already know them. E.g., "4 + 4" is a simple expression to say that the two given numbers need to be added. The expressions are made up of operands (values participating in the computation) and operators.

In programming, you use variables to hold values - so if you have two variables I and J, then expression "I + J" would mean the values of variables I and J need to be added. The two can, of course, be mixed as in "J + 4".

If you have used a spreadsheet program such as MS-Excel, you know how it uses the table cells to store everything - from input data, and intermediate results, to final output. does the same with the run-time data tree - use it to store everything. In , Nodes in the Data tree replace variables used in conventional programming. To extend the above example to , the expression would read "/VARIABLES/I + /VARIABLES/J", or if /VARIABLES is the context path, then simply "I + J".

Data Types

Data Types of the operands participating in an expression play an important role in how the expression is evaluated. For instance, the addition operation (+) is treated as a concatenation for string operands, and as numeric addition for numeric operands.

All programming languages need to know the data type of the operands - some expect to be explicitly declared, while others infer it implicitly. expects the Data types to be declared. When defining the TAG elements in your data schema, you specify a Data type.

Data type Description
STRING The most basic and generic data type - represents a string. E.g., "The quick brown fox jumps over the lazy dog".

NUMBER A whole number (or integer). E.g., 153, or 5318008.

DECIMAL A fractional (or a decimal) number. E.g., 3.14.

DATE A date without Time-zone. It is entered as a string in YYYY-MM-DD format. E.g., "1950-09-17"

DATETIME Similar to the DATE datatype, with added time information in HH:MM:SS format. E.g., "1969-07-21 02:56:15".

BOOLEAN A value evaluating to true or false. It is entered as a string and interpreted as follows. It the string can be read as an integer and is non-zero, evaluates to true, and if it cannot be converted to an integer, values "true", "yes", and "on" evaluate to true. Other values evaluate to false.

TYP:<Name> This is not a Data type by itself, but it is a notation used to support reusable data structure declarations. It declares a node referencing a name under TYPES node that has the actual structure declaration.

REF:<Name> This is like the TYP: declaration above but names another node within the schema itself (not under the types). This allows you to reuse the structure of another element already declared in the same schema.

EXT:<Name> A variation of the TYP: declaration, where the referenced TYPE structure can be extended by declaring more elements under it. So, the effective structure of this node is the structure copied from the referenced node and the extensions added under this node.
Data types used in .

Operators

The expressions are made up of operands (values participating in the computation) and operators (the operation). All programming languages support almost the same common set of operators, as does - and some additional ones.

Operator Rule Description
= The assignment operator. The value appearing to the right of the operator is copied to the node given on the left. Some rules apply here.
1 The left-hand side (LHS) of the assignment must be a Data path identifying a node in the tree. It cannot be a constant or another expression. The right-hand side (or the RHS) of the assignment can be a Data path, a constant or another expression. E.g., "/VARIABLES/I = /VARIABLES/J + 4" is a valid expression. Expressions "4 = 5" and "(/VARIABLES/I + 5) = 100" are invalid.
2 The data type of the LHS should be compatible to receive the value coming from the RHS.
3 If LHS is a STRING, it is compatible with all other Data types and before assignment the RHS is converted to string.
4 If LHS is a NUMBER or DECIMAL, an attempt is made to read the RHS as a NUMBER (or DECIMAL) and the resultant value is used, else a 0 is assigned.
5 If LHS is a DATE or DATETIME, an attempt is made to read the RHS as a date or datetime and then assigned. Otherwise, a blank is assigned.

+ The addition operator.
1 If both operands are numeric (NUMBER or DECIMAL), the result is the numeric addition of the numbers.
2 If the first operand is a STRING, the result is obtained by concatenating the two operands. E.g., '"Hello, " + 5' will result in the string "Hello, 5".
3 If the first operand is DATE or a DATETIME, the second operand is taken as a string and then read as a period specification (See next bullet). The result of the expression is the new date with the given period added to it.
4 A period specification in is a string composed of blocks each containing a number and a period specifier. E.g., "10Y 2M" means 10 years and 2 months. The period specifiers are- Y=Year, M=Month, D=day, h=hours, m=minutes, s=seconds.

- The subtraction operator.
1 If both operands are numeric (NUMBER or DECIMAL), the result is the numeric difference of the numbers.
2 If the first operand is DATE or a DATETIME, the second operand is taken as a string and then read as a period specification (As defined above under + operator). The result of the expression is the new date with the given period subtracted from it.
3 This operator is invalid for all other operand combinations.

+= The add and assign combination operator. The RHS of the expression is added to the LHS and then assigned back to the LHS.
1 As in the assignment operator, the LHS must be a Data path.
2 This operator is valid only for numeric operands. It is invalid for other Data types.

-= The subtract and assign combination operator. The RHS of the expression is subtracted from the LHS and then assigned back to the LHS.
1 As in the assignment operator, the LHS must be a Data path.
2 This operator is valid only for numeric operands. It is invalid for other Data types.

* The numeric multiplication operator. The result is the numeric product of the two operands.
1 This operator is valid only for numeric operands. It is invalid for other Data types.

/ The numeric division operator. The result is the numeric division of the two operands - first operand divided by the second.
1 This operator is valid only for numeric operands. It is invalid for other Data types.

% The mod or the remainder operator. The result is the value which is left as remainder when first operand is divided by the first. E.g., "7 % 5" will evaluate to 2. It is always between zero (inclusive) and the second operand (exclusive).
1 This operator is valid only for INTEGER (whole number) operands. It is invalid for other Data types.

~ The pattern match operator. The second operand is treated as a regular expression and matched against the first operand. Any resultant matching string is the result. If you have no prior knowledge of regular expressions, you can read up on it or take help from a programmer in your team.
1 Both operands are string types and all other Data types are automatically converted to strings before evaluation. there is no Data type restriction.
2 The second operand should be a valid regular expression, otherwise the result is a blank string.

~~ Match closeness operator. The result of this operator is a number between 0 and 100 suggesting how closely the strings resemble each other.
1 Both operands are string types and all other Data types are automatically converted to strings before evaluation. there is no Data type restriction.

== < > <= >= <> Comparison operators - equals, less that, greater than, less or equal, greater or equal, and not equal - respectively. The result is a Boolean value (true/false), comparisons are typically used in expressions used as conditions in "If" programming statement.
1 All these operators work on similar Data type rules and work differently for different operand types.
2 If both operands are strings, the operands are compared as strings, i.e., as per alphabetical ordering. The second operand is converted to string if necessary. So, "1" is greater than "09"
3 If any of the operands is a date, an attempt is made to convert the other operand to a date and then the operands are compared as dates, i.e., as per calendar ordering.
4 If any of the operands is numeric (INTEGER or DECIMAL), an attempt is made to convert the other operand to a number and then the operands are compared as numbers, i.e., as per value ordering. So, 1 is greater than "09" (converted to 9 as number).
5 If a Data type conversion is attempted and it fails, the evaluation of the expression is aborted immediately

&& The logical "and" operator. It expects each of its operands to be a Boolean value and the result is true if both the operands are true.

|| The logical "or" operator. It expects each of its operands to be a Boolean value and the result is true if any one of the operands is true.
1 It is important to note that in most programming languages, if the first operand is false in a logical "or" evaluation, the second operand is not evaluated at all. In , both operands (if they are sub-expressions) are evaluated even if the first one is false and there is no need to evaluate the second operand because the result of the evaluation does not depend on it. It may sound like a trivial detail but becomes important if the second sub-expression has side-effects like changing some value in the Data tree.

, The pass-through operator. This operator does not do anything, and the result is simply the value of the second operand. It is generally used to write multiple assignments in a single expression for compact code. E.g., "A = B, X = 5" will make two independent assignments.
Operators used in expressions.

Precedence

The expressions that you will typically write will be more complex than the simple expressions discussed so far. Even the most basic computation like addition will have two operators - one for computation and the other for assignment. More complex expressions will have even more. E.g., an expression like "A = B + C - 5". It has three operators in it. That is why you need to understand operator precedence.

Precedence decides in which order the operators are evaluated. Expression "A = B + 5" does not end up assigning B to A and then adding 5 to the result. This is because the assignment (=) has a lower precedence than the addition (+). The higher precedence operator is evaluated first, and that is why the result of adding B and 5 is assigned to A in this case. Within operators of same precedence, the evaluation is performed from left to right. As another example, expression "A = B + C * 5" will evaluate "C*5" first then add "B" to it and assign the result to A.

The operator groups in order or precedence from highest to lowest are-

  1. * / %
  2. + - ~ ~~
  3. == < > <= >= <>
  4. &&
  5. ||
  6. = += -=
  7. ,

If you have an expression that requires an order of evaluation different from the natural order, you can use parentheses to force an evaluation order. The content inside the parentheses is evaluated first, irrespective of the precedence of the operators. For instance by putting parentheses around "B + C" in the example above- "A = ( B + C ) * 5", the evaluation order is changed to evaluate "B + C" first. Parenthesized sub-expressions can be nested to create more complex expressions.

Pseudo Elements

adds certain attributes and data elements in the runtime Data tree in line with its abstraction approach. These pseudo attributes and elements are mainly used for easier access to some functions and to communicate information back to your programs. For example, when you execute a database operation, how do you know if the operation encountered an error. reports the status of the database operation through a Pseudo element (_STATUS) under the Table node. E.g., /Employee/_STATUS would contain the status of the last database operation on the table "Employee".

The names of all pseudo attributes and elements begin with an underscore (_), so it is advised that you do not use names in your schema that start with an underscore. The following is the complete list-

Pseudo Element Applies To Description (@.. are attributes).
/_LOCALS Inside Routine code This points to the local TAG declarations within the routine.

/_TODAY /VARIABLES The current date. I.e., the Data path /VARIABLES/_TODAY can be used to access the current date.

/_NOW /VARIABLES The current time.

/_HOSTNAME /VARIABLES The name of the server where your Web-API is executing.

/_HOSTIP /VARIABLES The IP address of the server where your Web-API is executing.

/_CLIENTIP /VARIABLES The IP address of the client from where your Web-API was invoked.

/_CLIENTISO /VARIABLES The 2-character code of the country from where your Web-API was invoked.

/_INSTANCE /VARIABLES A unique (sequential running number) for the current instance of this Web-API.

@_BASEURL /REQUEST The base URL of the server - it should be same as your Instance URL.

@_OAUTH /REQUEST The username of the user authenticated by OAuth. If the request had a valid authorization token, the corresponding username is passed here, otherwise it is blank. Please note that this value is set whether or not OAuth check is enabled for the service. This allows the service to implement its own security in conjunction with the OAuth mechanism. _OAUTH is also set if Oauth username and password are received with the request in the "Basic" header configuration. This allows a direct call to the service without performing an explicit authentication beforehand.

@_SERVER /REQUEST The Server name used while sending the request. The way HTTP DNS can be configured and with the use of HTTP forwarding, this can be different from "my.zoapiio.com"

@_PORT /REQUEST The HTTP Port on which the request was sent - it should typically be 443, the default for HTTPS.

@_PATH0 /REQUEST This would be same as the Web-API Entry point URL in your project.

@_PATH1, 2 .. /REQUEST When a request is received by server, it will accept URLs that have the ENTRY-POINT URL as the prefix. This mechanism is used to pass and receive parameters in the Web-API URL path. The components of the path following the base path are separated and stored in pseudo attributes PATH1, PATH2, and so on.

/_IN Inside ROUTINE or API code Inside a routine /_IN points to the input (first) parameter passed to it and for the API it points to the Input Message.

/_OUT Inside ROUTINE or API code Inside a routine /_OUT points to the output (second) parameter passed to it and for the API it points to the Output Message.

/_WHERE DATABASE-TABLE This is set by your program before invoking "Database open" command to specify the filtering for the results from the table. It should be syntactically correct "Where" portion of the SQL query that will get the results. E.g., /Employee/_WHERE = "Department = 'HR'"

/_ORDERBY DATABASE-TABLE This is set by your program before invoking "Database open" command to specify the ordering of the results from the table. It should be syntactically correct "Order By" portion of the SQL query that will get the results.

/_LIMIT DATABASE-TABLE This is set by your program before invoking "Database open" command to specify a limit on the maximum number of rows to retrieve.

/_STATUS DATABASE-TABLE, DATABASE-QUERY, MONGO-COLLECTION This is set as a result of a Database operation. A value of zero (0) indicates success and any other value means an error.

/_STATUSTEXT DATABASE-TABLE, DATABASE-QUERY, MONGO-COLLECTION This is set as a result of a Database operation and contains the textual explanation of the Status code.

/_EXECUTEJS WEB-SCRAPER Assigning a value (should be a valid JavaScript) to this pseudo variable causes the script to be executed in the scraper session.

/_document MONGO-COLLECTION Represents the JSON document for storage in a MongoDB collection. Before calling a save or update operation, the application must set it and after a read operation, the application can access the document from this.

/_id MONGO-COLLECTION Represents the Mongo Document Id. For a fetch operation, the application must set it and after a save operation, the Id can be retrieved from here.

@_SESSIONID /SESSION A unique Id of your session.

@_READONLY /SESSION A value you can set in your program to indicate to that the contents of the SESSION should not be saved when the service completes.

@_COUNT TAG Returns the number of instances of the TAG that are present in the Data tree.

@_NODENAME TAG Returns the name of the Tag (as in definition).

@_XML TAG Represents the Serialized XML of the node. You can read this value to get the XML and you can assign a value to this, which will result in the given XML to be extracted under the node.

@_JSON TAG Represents the Serialized JSON of the node. You can read this value to get the JSON string and you can assign a value to this, which will result in the given JSON to be extracted under the node.

@_BASE64 TAG (STRING) Represents the Base64 encoded value of the contents of the node.

@_YY TAG (DATE and DATETIME) The 2-character year component of the date.

@_YYYY TAG (DATE and DATETIME) The 4-character year component of the date.

@_QUARTER TAG (DATE and DATETIME) The quarter of the year in which the date falls.

@_M TAG (DATE and DATETIME) The month component of the date without zero padding on left.

@_MM TAG (DATE and DATETIME) The 2-digit month component of the date, zero padded if necessary.

@_MON TAG (DATE and DATETIME) The 3-character (short) name of the month component of the date.

@_MONTH TAG (DATE and DATETIME) The full name of the month of the date.

@_D TAG (DATE and DATETIME) The date component of the date without zero padding on left.

@_DD TAG (DATE and DATETIME) The 2-digit date component of the date, zero padded if necessary.

@_DAY TAG (DATE and DATETIME) A string representation of the Day name.

@_DOW TAG (DATE and DATETIME) A single digit number indicating the day of the Week.

@_hh TAG (DATETIME) The 2-character hours component of the time.

@_mm TAG (DATETIME) The 2-character minutes component of the time.

@_ss TAG (DATETIME) The 2-character seconds component of the time.

@__{MethodName} TAG This a short-cut method to invoke a Method that will receive the node as input. This evaluates to the return value from the Method.
Pseudo Elements used in the Data tree.

The following pseudo elements can be used to dynamically override values in your project config.

Pseudo Element Applies To Description (@.. are attributes).
@_URL WEB-SERVICE Assigning a value to this attribute will override the value of URL for the Web Service. The assignment should be done prior to calling the service.

@_SOAPACTION WEB-SERVICE Assigning a value to this attribute will override the value of SOAP-ACTION for the Web Service, if it is a SOAP service. The assignment should be done prior to calling the service.

@_CURLOPTIONS WEB-SERVICE Assigning a value to this attribute will override the value of CURL-OPTIONS for the Web Service, if it is configured to use curl for invocation. The assignment should be done prior to calling the service.
Pseudo Elements used to override options in .

Statements

The statements (or commands) are what you use in your program to do things. They are the basic building blocks of your program, and you put them in the right order to convert your business algorithm into a working program. In Web-IDE, you do not need to remember any command names as the drag-drop intuitive UI does it all for you.

Statement Description
// The comment - it is ignored at the time of execution. You will use this to add descriptive text in your program to make it more readable.

Abort Aborts the execution of the service immediately.

Break Breaks out of the innermost iteration and advances to the next statement.

Compute This will take an expression and evaluate it. The most common use for this is to move values around in the Data tree.

Call This calls a Java method in your program.

Continue Skip the rest of the current iteration block and proceed to next iteration.

Database This is used to perform a database operation such as fetch or save data rows.

DbQuery Database Queries in your project are used for more complex reads and updates in your database. [SQL programming knowledge is required]. The DbQuery statement operates on a database query.

Declare It declares a local variable inside a ROUTINE and then accessed as /_LOCALS/Name.

Execute Executes a Routine in your project.

Execute2 It is a variant of Execute above - it executes the program associated with another Web-API (part of the same Project), without invoking it as a service.

ExportXml It exports a node into a serialized XML string. The Pseudo attribute "_XML" does the same, but this allows you to attach an XML namespace while doing the export.

ForEach Iterate over all instances of a Node (by name) - requires a block of statements.

if A compound statement allowing conditional execution - requires a condition and a block of statements. Optionally the if block can have any number of following "else if" blocks.

JmsSend Sends an MQ message to an MQ (JMS) destination.

Node Performs miscellaneous operations on the nodes in the Data tree.

NodeCopy Copy the complete sub-tree under a a node to another node.

NodeInit Initializes the content of a node from a static XML string (separately defined in the same project.

Return Return from the currently executing Routine or Web-Service immediately.

Sleep Sleep, or create a delay of given number of milliseconds.

WsCall Call (invoke) a Web-Service (or Web-API) - the invoked API can be any Web-service, not necessarily hosted on . The call is initiated asynchronously, allowing you to launch parallel requests. You must use WsControl to wait for the request to finish.

While Execute the given statement block, while the condition is true. The condition is evaluated each time before entering the loop and it stops when the condition becomes false.

With Like ForEach, except the block executes only once.

WsControl Control (stop or wait for) a previously called Web-Service.

WebScrape Execute a command in the Web Scraping session. Compute statements are used to set and get values to/from a web page in a scraping session.

WebSocketGet Used to receive data from the socket channel in a WebSocket service.

WebSocketSend Used to write data to the socket channel in a WebSocket service.

WsSyncCall A WsCall that executes synchronously. I.e., it waits for the call to complete before returning.

Xslt Performs Xslt based transformation. [Xsl programming knowledge is required]
Executable statements used in programming.

Iterating over Nodes/Rows

One the things you will find yourself doing very frequently in your programs is iterating over a set of nodes. Typically, when your program receives an input message containing a list, you must process all items in the list. Another similar requirement is when you read a database and you must process all rows that are in the result set.

In abstraction world, both these situations are treated as the same. That a Database is a different entity from a Data tree node, is hidden from you and you view each case as a single case of iterating over a set. The "ForEach" statement is used for iterating over a set. You specify a Data path to represent the set - this is best understood through the examples-

  1. /REQUEST/Employee would represent all "Employee" elements under "/REQUEST". The ForEach loop will start at the first Employee node and then proceed sequentially through the list.
  2. The Data path /REQUEST/Employee[3], would start at the 3rd Employee node and will continue up to the end.
  3. If "Employee" is a DB table in your project, then the Data path /Employee, would represent all rows in the currently open result set on the table. When the loop completes, the system automatically advances to the next row in the result set. The result set is opened using "Database open" or "DbQuery open" statements.

The ForEach statement allows an optional "Where" condition, which causes the loop to skip over nodes where the given expression evaluates to false. This also works with Database Tables and MongoDB collections. When an expression is used when looping over Database or Mongo nodes, the Database/Collection open and close operations are automatically performed using the expression provided - no explicit open/close is required.

Loop Variable

With the "ForEach" statement you can specify a Loop Variable - the name of a Data element declared under /_LOCALS or /VARIABLES with Data type "NUMBER". If a loop variable has been specified, it will be updated with every iteration to indicate the sequence number of the current loop, starting at 1.

Web-API Security

The Internet is a public medium, and unless the information your Web-API deals with is free and public, it needs to be protected from unauthorized use. For starters, it is recommended that you use the secure HTTP (or HTTPS) for endpoints of your Web-API. This ensures that the data being exchanged cannot be read by a third-party and only the sender and receiver can see its contents.

A basic security mechanism can be used that requires every request to be accompanied by a username and a password. The username and password are sent with the request as HTTP headers and before the service is invoked the credentials are verified against stored usernames and passwords.

Currently, the most popular authentication mechanism is the one using OAuth. This requires the username and the password to be sent only once to an authentication service. The authentication service returns a token which can be used as an authentication substitute in subsequent calls.

hosted application containers use HTTPS for all communication. Additionally, also manages the authentication for your services - both Basic and OAuth are supported. It allows you to store your username passwords for each service and automatically authenticate the clients. You can choose between basic security and OAuth based security. Typically, you will disable the security during the development stage and at the time of deploying the Web-API, you will enable it.

This is optional and the hosted Web-APIs can choose to implement their own authentication.

Wizard generated applications have OAuth security enabled based on the user accounts in the application itself.

Lastly, a firewall type of control can be applied on the Web-APIs so that only the requests originating from a specified set of IP addresses are entertained. runtime allows you to apply IP address controls on the Web-APIs.


Step Seq Description
Create Username/password database 1 Login to the Zoapiio.com website using your access credentials
2 From your control panel, select "API Access" from menu
3 On the page, create the usernames and respective passwords.

Choose API security 1 Login to the Web-IDE using your developer password.
2 Create a new project or open an existing project.
3 Create a new Web-API by selecting "New ENTRY-POINT" from the context menu under "Business Flows" node in the schema. Or select an existing ENTRY-POINT.
4 On the properties page of the ENTRY-POINT, select the security mechanism you want to use.

Know the API URL 1 Before the Web-API that you have built can be called from a client application, you must know its URL.
2 The URL of the Web-API is constructed by prefixing your dedicated container URL to the URL you have specified with your Web-API (ENTRY-POINT).
3 The URL of your container is- "https://my.zoapiio.com/{your instance code}". You can get your instance code from the account panel, where you signed-up. It is also visible in the URL of the Web-IDE page.
4 requires all HTTP service URLS to start with "/wc". So, if your Instance code is "ABC" and your Web-API URL is "/wc/myapi", then the service can be reached at the URL "https://my.zoapiio.com/ABC/wc/myapi".

Authentication APIs 1 Please note that the development of the client to consume the API requires knowledge of programming.

2 Also note that, if you are using the Application Wizard to generate your application, the front-end of the generated application automatically manages this for you.

There are two APIs provided by for authentication.
3 /auth/authenticate (prefixed with your container URL). Your client application will send the user credentials using the HTTP Basic authentication mechanism. This means that the request will contain the following HTTP header. Please lookup up the "Basic HTTP authentication" on the web for details.

Authorization: Basic [Base64(username:password)]

The service will return a single text line containing "FAILED" (in case of failure) or "OK " followed by the authentication token (in case of success).
4 /auth/validate (prefixed with your container URL). Your client application will send the user credentials using the HTTP Bearer (OAuth) authentication mechanism. This means that the request will contain the following HTTP header. Please lookup up the "OAuth HTTP authentication" on the web for details.

Authorization: Bearer [Authorization token]

The service will return a single text line containing "FAILED" (in case of failure) or "OK " followed by the user name, using which the authentication was performed (in case of success).
5 You do not need to explicitly call the validate API and is only provided as a blank call to verify that your token is valid and current. For Web-APIs configured to use API Security, every request will be automatically validated.

Call the APIs 1 The Web-API will typically be called from a browser-based application or from another server application.
2 The mechanism of passing the authentication information is same in each case. In case of a browser application, however, you may want to save the "Authentication Token" in a browser cookie, so that your application always has easy access to it. It will be required with every call.
3 Your first call to the server in a session would be to the authentication service.
4 Once a successful authentication is performed, the client application will send the authentication token with every following request in the session using the OAuth mechanism described in the validation API above.
5 Tip: Generally, during the building phase, you may want to keep the API security off or restricted by IP address alone, so that it does not inconvenience your testing process. Once you are ready to roll it out for to your users, you can enable the API OAuth security.
Using to manage your API Security.

User Session

Cookies

User Session represents the information about a client (or user) that is using your application (or services). The session works through HTTP cookies - same Cookies that the websites you visit store on your computer to remember you. You will need to pick a name for the Cookie that will serve this purpose and publish it to the users of your Web-APIs. The clients need to receive this Cookie from the Web-API responses and return with every request to maintain the session. The Web browsers already do that - they remember and return all cookies; your clients need to replicate the same behavior.

The SESSION node in your Schema serves as your store for the user session information. What information you store there and when it is created or updated is up to you. You specify the name of the Cookie that you have picked for session tracking and specify it with the SESSION properties. The same Cookie also needs to be declared under the COOKIES node in the Schema. You will then define the structure of your Session data under the SESSION node and that is all. takes the responsibility of saving the session information and making available to all your Web-APIs.

JSON Web Token (JWT)

An alternative to Cookies based Session Id, is the JWT. JWT is a more modern approach, and it uses OAuth2. Most customer facing applications, including ZOAPIIO Web and mobile apps, use this approach.

While the Cookie transmission is handled by the browser, the JWT needs to be explicitly added to the HTTP request by the application. Everything else remains the same. You can configure the ZOAPIIO Session to use either of the two mechanisms.

Relational Databases

If you are developing business modules or Web-APIs, chances are you will need to store and retrieve tabular data. Relational databases (RDBMS) are a popular way to store application data in an efficient way. To build database access into your Web-APIs, you do not need to know any technical details about database programming. However, acquiring a high-level overview of SQL is advised. If you have not used databases or SQL before, you should be able to find introductory tutorials on the Internet.

uses two major abstractions for database access - DATABASE-TABLE and DATABASE-QUERY. Default subscription comes with one RDBMS instance configured for you - for most cases that is enough. runtime allows you to query and update the tables in the database, but the tables need to be created in advance. Usually, the design of the database if one the first activities in application development.

Use the DB assistant to manage your database from the web. You can create, delete and alter tables; import data from CSV files; besides viewing and updating the data.

In your project Schema, create a DATABASE-TABLE node to gain access to a table in the database. The DATABASE-TABLE node will allow you to query and iterate over the table rows and make updates and inserts. If you have more complex queries - both query and updates/inserts - you can use the DATABASE-QUERY node. However, for typical database operations, DATABASE-TABLE is enough.

Database table access is done using the Database statement.

  1. You create the table in the database first. The table creation is automatically handled if you are using the Application Wizard. If you are not using wizard, you will use the DB Assistant to create your table.
  2. Declare the DATABASE-TABLE node in the schema and import its definition from the server.
  3. To Fetch a record using the key, simply assign the value of the Key and do Database fetch. Process the data. E.g.

    /Employee/Id = 100
    Database fetch Employee
    /Response/Name = /Employee/Name
    ...
    			

    It is advisable to check /_STATUS for failure.
  4. To open a cursor and process all records, use either

    /Employee/_WHERE = "Name = 'John'"
    Database open Employee
    ForEach /Employee
    ...
    End ForEach
    Database close Employee
    			

    or

    ForEach /Employee Where Name == "John"
    ...
    End ForEach
    			
Database Queries

For most common situations of database access, you should never need to use Database Queries. This is an advanced subject and requires the knowledge of SQL syntax - if you do need to use Queries and do not know SQL, you should take the help of a programmer in your team. SQL is quite simple in syntax; you should also be able to write simple SQL statements with some help from Google. You should use Database Queries, when-

  1. You need to use group functions like Sum(), Count(), etc. with or without the Group By SQL clause.
  2. You need to fetch rows from the database by joining two or more tables.
  3. You need to fetch or update the database using SQL statements that have substitution parameters.
  4. Other advanced database access needs like dynamic SQL.
Query Parameters

SQL query processing engine allows a query to be executed which has placeholders in it for values to be provided separately. The parameters are positional parameters meaning they are referenced by position and not by name. The Query string will have &1, &2 etc. as positional placeholders and will be substituted with values from the parameter list.

lets you have access to this feature of SQL engine, and takes it a step further. You can have the placeholders in your SQL query which will be passed to the SQL engine. In addition, it allows you to flag some parameters for "Inline Replacement". This means that these parameters are substituted into the query string by runtime, even before passing it to the SQL processing engine. This method of substitution allows you to even replace keywords within the query - something that SQL parameter substitution does not allow.

Step Seq Description
Define the Query 1 Add a DATABASE-QUERY Tag to your project. The queries can be read or update and should be appropriately flagged.
2 Enter your SQL statement with placeholder parameters if any.
3 Under the DATABASE-QUERY Tag, create a QUERY-PARAMETER Tag for each parameter you have used. Declare them in the same order as they appear in the query string. The Query Parameters will have names, even though are positional so that they can be accessed inside the programs.
4 If your query is a read query, then for each Column that is part of the result set, declare a TAG Tag under the DATABASE-QUERY and given them proper Data types. The WebIDE has a context menu command to automatically create the TAG names from the query.

Access the Query 1 Inside your program, assign the values to the parameters using their Data path- /{Query-name}/{parameter-name}.
2 Then use the DbQuery statement to execute the query.
3 If this was a read query, run a ForEach look on the query Tag and process the results.
Using Database Queries in your project.

Dynamic SQL

If your application requires the use of dynamic SQL, you can handle it by-

  1. Defining a Database Query with one "inline Substitution" parameter containing the entire Query, or.
  2. Assigning a value to _SQL attribute of the DATABASE-QUERY node with the dynamic SQL. If you have defined any Query Parameters, then the SQL you assign here must have the same number/type of Parameter placeholders - represented by a ? (SQL syntax).

Mongo Databases

MongoDB from Google is a no-SQL database. It has been optimized for specific types of use-cases that deal with JSON documents. There are other no-SQL databases in technology scape, but MongoDB has gained a large following and is by far the most popular.

If your application requires the use of MongoDB, ZOAPIIO has an abstraction for it.

There is no utility in ZOAPIIO similar to the Relational DB assistant. The only access is through the APIs.

For details, refer to the Reference Guide.

Background Jobs

Background Jobs are needed to perform daemon functionality. allows you to create any number of background jobs in your application.

  1. Create an ENTRY-POINT service that runs in an infinite loop. I.e. it runs perpetually in a loop performing a certain task and then waiting for a while. The wait is essential otherwise the service can overload your application and affect performance.
  2. Launch the service from the Application initialization section of the DECLARATIONS area in your project. Add the following line inside the onInitialize() function.
public void onInitialize(Node node) {
	spawn("/wc/... (Service URL)", "<REQUEST></REQUEST> (The Request XML for the service)");
}
   	

Scraping Web data sources

supports web scraping using a Selenium driver interface. Your default instance (free tier) does not have a scraping pool configured. You can upgrade to a paid instance and request for a scraping pool to be configured according to your needs. See the Reference Guide at the end of this document for full description of scraping commands.

  1. You script the scraping session starting with an 'open' command and ending with the 'close' command.
  2. You script the scraping session by interacting with the page and controlling it in the script.
  3. The elements on the page are referenced using Data Path syntax.
  4. To get contents from the page or to type values into input fields, you use the 'Compute' statement.
  5. To otherwise interact with the page like clicking on elements, you use the scraper commands.
  6. To Execute a JavaScript inside the page, put the JavaScript in a string and then assign it to the {Scraper}/_EXECUTEJS pseudo node.

Edge node architecture

The default configuration of the Selenium session is to invoke a real browser program (Firefox, or Chrome etc.) that runs in a virtual X environment. This means that the browser is not visible as a window. Since the scraper script is executing on the server, which does not have a console, this becomes a necessity. Please note that the 'screenshot' scraper command works for the virtual environment as well. So, it would produce a real image of the contents of the browser window.

supports another architecture for scraper configuration which allows the scraping agents to be opened on computers other than the server running the scraping script. There is a standalone 'dumb' edge scraping agent, which runs the browser under the control of the server.

  1. Any number of edge nodes can be provisioned in the scraper pool.
  2. The edge nodes can be on desktop or laptop computers running on home or office networks.
  3. The browsers running on edge produce visible windows and can even be manually interacted while the server is controlling it.
  4. The requirement is that the edge node and the server must be able to connect with each other using an IP address.
  5. In home or NATted office networks, this is not possible. To deal with such situations a VPN or a port forwarding mechanism can be set up that will enable this. Please consult a networking specialist for details.

Application Properties

Application Properties are system wide fixed settings (or constants), which are used at multiple places in your application. Your project simply references these settings by name. These settings are kept at a common place (file, a database table or even on the Internet). If these values change, only the common store needs to be updated without impacting your application.

allows you to configure and use application properties using a database table. Files cannot be used because you do not have direct access to your container, but Web-IDE has the DB assistant tool to let you access your databases. Your instance comes pre-configured with a database table for this purpose and is mapped to a property set, that is available for access in your programs. The table should be named "Z_Properties" and should be mapped to a property set "MainProps".

Step Seq Description
Define Properties 1 Launch the "DB Assistant" tool from your Web-IDE session. You should see your configured database and the list of tables under it.
2 Locate the table Z_Properties - this is your properties table. Make sure you do not drop or alter this table in anyway.
3 Right click on the table and click "Select From", then follow the UI to see the current settings.
4 Use "Insert Into" or "Update" menu commands to create or change settings. You can leave the "Locale" column blank. Also, the property names are usually components separated by a dot (.). E.g., company.name.shortname, company.name.fullname - this makes the naming structured and intuitive.

Access the Properties 1 The Property set can be accessed inside your project with PROPERTY-SET Tag. Under project root, add the PROPERTY-SET and select "MainProps" from the drop-down.
2 You can now access properties using Data path /MainProps/{property-name}. When using the property name substitute the dot (.) characters with underscore (_). So company.name.shortname should be accessed as /MainProps/company_name_shortname.
Using Application Properties in your project.

Using Java

The scripting is very high-level, powerful, and compact. It is designed to help ease the development of Web-APIs. However, it cannot replace a conventional programming language on the grounds of flexibility. An example is formatting values. A language like Java offers string processing tools that can let you reformat data in the way you desire. Should your project have a need for such processing, you can use Java Methods in your project.

When writing the Java code, you can access the Schema contents using built-in functions (methods), as described below. The Java functions also allow you to access other features in the system, which have not been abstracted through the business rules.

If the processing you want to perform using Java is simple and can be expressed in a few lines of Java code, you can use the "Java" business rule and write the code in-line embedded within your rules. For more complex processing use the METHOD node, described below.

Please note that the knowledge of Core Java and Java DOM API is required. If necessary, take help of an experienced Java programmer in your team.

Step Seq Description
Code your Method 1 You declare the Java methods in your project by adding a "METHOD" node in the schema.
2 The code inside the method looks like any Java method and it has a fixed prototype. It receives two objects of class org.w3c.dom.Node. They are called 'in' and 'out', to represent an input node and the output node. There is no restriction, however, on how you use them. You can read and update both nodes.
3 The Java methods in you your project inherit some key methods from its parent class. The most commonly used methods are "get" and "set", which allow you access to the contents of the Data tree.
get(Node contextnode, String path): will return you the value in the node represented by the path. If the path is not an absolute path. (I.e. does not start with a "/"), the path is searched under the context node. You can use Method parameters (in or out) as the context path.
get(Node contextnode, String path, String value): will set the value in the node represented by the path.
4 Strict warning: Do not manipulate the contents of the nodes and the Data tree using Java DOM API methods. Your program will crash.

Call the Method 1 The Java method can be called from your Web-API program using the Call statement. You pass the two parameters to the Method - both must be Data paths identifying the nodes in the Data tree.
2 To save a lot of repetitive declaration, make user of the TYPES feature.
Using Java inside your project.

Security related Restriction

There are certain restrictions on how you write the Java modules, for the reasons of security.

  1. You cannot use the following global objects/classes/keywords of Java - System, management, Class, and package.
  2. ZOAPIIO has a built-in method runCommand which executes shell commands and is reserved for internal use. It cannot be used in your programs.
  3. You cannot use the getClass and forName methods of Java.
  4. When using the 'new' keyword of Java you must provide the full Class name of the object being instantiated. You can only create objects from the following Java packages - java.lang, java.util, java.text, java.time, org.json and java.io (Some java.io Classes may not be allowed).
  5. If you want to declare a local class in your program, the name must start with an underscore (_), and you can use the 'new' keyword to instantiate it.

Built-in Functions

The following functions (methods inherited from base implementation) can be directly called from your Java code.

Function Description
Data access.
String get(Node node, String path); Read and return an element from the contents of the current Document (schema). The second parameter is the element's path. The first parameter is the node, relative to which the path is interpreted. When a method is called, two Node parameters are passed as parameters to it. If the path is absolute (starting with a /), the node has no significance, but a non-null value must be passed.

void set(Node node, String path, String value); Update an element in the current Document (scheme). First two parameters are same as for get above. The value to be set is the additional third parameter.

Node resolvePath(String path, Node ref, boolean create); When navigating the document tree, it is sometimes useful to resolve an intermediate node and then continue traversal relative to that. This method can be used for that. It does not return the contents of the node pointed to by path, but the node itself. The returned node can then be used in other calls to get, set, or resolvePath. If create is true the node is created if not already present. If resolution fails, a null is returned.
General utilities.
String getURL(String url);
String getURL(String url, String postdata);
ZOAPIIO has elaborate support for calling APIs as already explained in this guide. Sometimes, it is more convenient to simply call a URL using GET or POST method. getURL method lets you do just that. If postdata is provided, it becomes a POST call and the provided data is passed as contents for the post. The result is returned as a String.

long getUniqueNumber (String key); This returns a system-wide Unique number within the scope of the key provided. The returned number are sequential running numbers.

float parseFloat(String f);
float parseFloat(String f, float def);
A convenient method to parse a float number from the given string. If parsing fails, the default (second parameter) is returned. If default is not provided, zero is returned.

int parseInt(String num);
int parseInt(String num, int def);
Like parseFloat - equivalent functionality for parsing integers from String.

String randomWord(int size);
String randomWord(int size, boolean allowspace);
Create a random word (not a dictionary word) of given size and return.

String randomNumericWord(int size); Create a random numeric string (integer) of given size and return.

String randomPhrase(); Return a random phrase.

int randomInt(int min, int max); Returns a random integer.

double randomGaussian(int mean, int stddev); Returns a random Gaussian double precision number.
Encryption.
String encryptString(String data);
String encryptString(String data, String password);
Encrypts the given string using DES (reversible) encryption. If a password if provided, it is used for encryption - otherwise, the default encryption key set for your container is used.

String decryptString(String data);
String decryptString(String data, String password);
Corresponding decryption functions.

String b64digest(String data);
String b64digest(String data, String algorithm);

This function creates a digest (one-way hash) of the input data using the given hash algorithm (must be one of 'MD5', 'SHA-1', or 'SHA-256'). The algorithm parameter is optional and defaults to MD5.

Since the digest is a binary value, it is Base64 encoded so that it can be stored and used as a string.


String hexdigest(String data);
String hexdigest(String data, String algorithm);
Same as b64digest (above) except that the result is HEX encoded instead of Base64.
JWT Management.
String getJWTToken(String subject, String scope, String userid, String other);

Creates and returns a JWT, signed using the Server's configured secret key. The key is configured by the system administrator and generally you do not need to know what it is. The same key is used when resolving the JWT (See below).

The JWT is created with four fields in it - subject, scope, userid, and other. With , you can run multiple applications in the same instance. Each user application will have its own user space and users of one cannot be mixed with others. The subject is typically the name of the application, and scope is any arbitrary chosen value to segregate the user scope. userid is a unique identification of the user and the other field can contain any extra information that needs to be put into (and later retrieved) the token.


String getJWTToken(byte[] secret, String subject, String scope, String userid, String other);
This is same as the getJWTToken() above, except you provide the key for signing the token.

String resolveJWTToken(String jwt, String scope); Resolves the JWT (using the server's secret key), verifies the scope value present in the JWT matches the provided scope and returns the value of the userid field if check succeeds. Upon failure, null is returned.

String[] resolveJWTToken(String jwt, String[] fields); This is a variation of the resolveJWTToken method, which verifies the signature and then returns one or more fields from the token. The fields that need to be returned are specified as second parameter. E.g. if fields is set to ["subject","userid"], the values of subject and userid will be returned. The return value is either null (if signature verification fails) or a String array with as many elements as in the input parameter with respective values.

String getBasicOAuthToken(String user, String pass);
Create a Basic OAuth Token from the given Username and password. This simply puts the user information in correct format and encodes it.
Create ZIP (Compressed) files.
Object openZipFile(); This and the next two methods, provide you a convenient mechanism to create ZIP compressed files. You initialize the zip file using this method. The initialized ZIP file is temporary - it is deleted when closed. The method returns a handle Object to the created file, which should be used in subsequent calls to operate on it.

void addZipEntry(Object zip, String path, String contents, boolean mmdecode); Adds a file to the ZIP. The path is the path of the file in the ZIP, and the contents are provided as a String. The mmendecode parameter indicates that the contents are Base64 encoded and should be decoded before storing in the ZIP. When adding binary files, you should Base64 encode it and specify this flag as true.

void dumpZipFile(Object zip, OutputStream out); This call is made to close the ZIP file and return the contents. The ZIP contents must be received in an OutputStream Java object. The temporary ZIP files are deleted after this call.
Temporary file storage.
Object openTempFile();
Object openTempFile(String name);
This and the next four calls below allow you to create temporary files. Use this to create a temporary file - the handle Object is returned which is used in subsequent operations on the file.

void appendTempFile(Object tempfile, String data);
void appendTempFile(Object tempfile, byte[] data);
You can append string or binary data to the temp file.

void deleteTempFile(Object tempfile); The temporary file is deleted.

String nameTempFile(Object tempfile); Returns the name of the temp file.

byte[] getTempFile(Object tempfile);
BufferedReader readerTempFile(Object tempfile) throws IOException;
These calls are used to get or read the contents of the temp file.
Read and create PDF files.
Object openPDFDocument();
Object openPDFDocument(String b64data);
This and the following calls allow you to read and create PDF documents. This creates or opens a PDF document and returns a handle to it. The handle is used in the subsequent calls. The data for existing documents is provided as Base64 encoded binary data.

void addPDFImage(Object pdf, String data); Append an image to the PDF document. The data is provided as Base64 encoded string representation of the image.

void addPDFDocument(Object pdf, String data, int[] pages); Append pages from another PDF document. The other PDF document should be Base64 encoded and passed as data parameter. The list of pages to copy from the other PDF document is passed as the last parameter.

String closePDFDocument(Object pdf); This closes the PDF document, discards the context, and returns the contents in Base64 representation.

Object[] splitPDFDocument(Object pdf); This splits the PDF document into pages. Each page becomes an independent PDF document, and the resultant array is returned. Each page can then be separately processed.

String imageFromPDFDocument(Object pdf, String type); This assumes that the PDF document contains an image, extracts it and returns. If multiple images are present such as in header or footer of the document, it selects the largest one, assuming that is the primary image on the page. The type can be "png", "jpg", etc. and the returned image is in that format with Base64 encoding.

String htextFromPDFDocument(Object pdf); Extracts readable text from the PDF document in hypertext format. See OCR and PDF Parsing for details.
Create Excel (spreadsheet) files.
Object openExcelDocument(); This and the next two calls allow you to create Excel (xlsx) documents. This starts a new Excel document and returns a handle to it. The handle is used in the subsequent calls.

void addExcelCel(Object xls, int row, int col, String data); Use this to add contents to a cell within the Excel document.

String closeExcelDocument(Object xls); This closes the Excel document, discards the context, and return the contents in Base64 representation.
Data format conversion.
String pdf2html(String b64data); Convert a pdf document (Base64 data) into HTML and return.

String image2thumbnail(String b64data, String contenttype); Create a thumbnail from an Image.

String docx2html(String b64data); Convert Word document (docx) to HTML and return.

String docx2text(String b64data); Convert Word document (docx) to text and return.

String xlsx2text(String b64data); Convert Excel (xslx) document to text and return.

String html2text(String data); Convert HTML document to text and return.

String pdf2text(String b64data); Convert a pdf document (Base64 data) into text and return.

String[] pdf2image(String b64data, String imagetype,
  String ioptions);
This assumes that the PDF is composed of images. It breaks the document into multiple images of the given imagetype and returns as an array. The returned data is in Base64 encoding. ZOAPIIO uses ImageMagick to do this conversion, the command line options for which can be passed as ioptions parameter.

String xml2json(String xml); Convert an XML to JSON format.

String[] splitCSV(String csvrow); Takes a single Comma Separated Values row and breaks it into individual values, taking care of quotes and removing them in the process.
OCR and PDF parsing.
String image2htext(String b64data, String ioptions, String toptions); This allows you to perform OCR operation on an image and return the result as an XML String, which contains recognized text and position attributes. See OCR and PDF Parsing for details. Before running the OCR, you can apply transformations on the image. ZOAPIIO uses imageMagick on the server, and you can pass image processing options (imageMagick convert command line options) as second parameter. Tesseract command line options can be passed as the third parameter. See online documentation on tesseract. Both image and tesseract options parameter can be null, implying defaults.

String pdf2htext(String b64data); This allows you to extract text from a Text mode PDF in the hyper text format similar to the OCR operation (althouth no OCR is actually required). See OCR and PDF Parsing for details.

String htext2map(String htext, String templatejson,
  String[] resulttemplate, String[] retult);
This allows you to further process the recognition results in htext format into meaningful content. See OCR and PDF Parsing for details.
XML parsing/serialization.
Document parseToDOM(InputStream in);
Document parseToDOM(String in);
Parse an XML string into DOM.

String renderAsXML(Node node); Render an XML node as a string.
Character escaping.
String URLSafe(String s); Make a string safe to be included in a URL as a query parameter.

String XMLSafe(String s); Make a string safe to be included in an XML string.

String SQLSafe(String s); Make a string safe to be included in a SQL string.

String JavaScriptSafe(String s); Make a string safe to be included in a JavaScript code stub.
Miscellaneous.
javax.mail.Message getEmailMessage(Node node); When writing handler for ENTRY-POINT-EMAIL, you need to access the Email message that has been received. The Java Email Message object is too complex to be abstracted into business rules, so you must write the handler in Java. This call allows you to retrieve the message for processing.

String verifyFacebookToken(String appid, String userid, String token); Server-side verification of the Facebook token returned when using 'Sign-In with FaceBook'. The FaceBook browser integration returns a userid and the token - both must be provided for verification. The JSON object containing the user details is returned.

String verifyGoogleToken(String appid, String userid, String token); Server-side verification of the Google token returned when using 'Sign-In with Google'. The Google browser integration returns a token - the token and the Google registered appid must be provided for verification. The JSON object containing the user details is returned.
Built-In Java functions in your project.


jQuery Java Adaptation

aims to make data processing flexible, easy and compact. A very popular product - jQuery - also has the same goals with respect to processing data in JavaScript (front-end programming). If you are a jQuery programmer, you have another option to process the data in your Project schema.

provides an adaptation of jQuery core functions in Java, allowing you to query and update the data using jQuery like syntax. Let us start with an example-

final float accum[]=new float[1];
accum[0]=(float)0.0;
$(in).select("AirInfo > AdditionalDetails > PassengerInfo PaymentReceived")
	.each(new $Operator() {
		public void operate(int seqno, Node n) {
			accum[0]+=parseFloat(get(n));
		}
	});
	
  1. Wrap a Java node reference (usually received as parameter to a Method) in $() to enter into jQuery mode.
  2. Inline function can be created to emulate anonymous functions of JavaScript used in jQuery.
  3. Create an object of class $Operator and override the operate method which receives the sequence number and the Java node reference as parameters.
  4. The operate function can access variables outside its scope subject to restrictions placed by the Java language - these variables should be declared final. You can declare them as final Arrays if you need to update the contents inside.
  5. The example above uses an array of 1 element to achieve this.
  6. See the reference below for full details.

Class/Method Description
$() Enclose a Java node reference inside $() to start using jQuery functions on it.

$Operator Local class to create an anonymous function for jQuery mode operations.

selector

Selector is a string that lets you define a criteria for selecting the first node in the tree under the root on which the .select function is invoked.

It resembles a jQuery selector but does not support all features of the jQuery selector. Supported features are-

  1. >: Used as separator between node names, implies only immediate children would be considered for matching the next name.
  2. Space separator: When space is used as a separator between names, it implies any descendent node can match.
  3. :eq(): Used for index selection, will select only one, as pointed to by the index, node from a list.
  4. [name=val]: Used for attribute selection, only nodes with attribute name matches given value will be matched.

.select(String selector)

This will select the first node that are matched by the given selector, under the root. This is a key difference from the jQuery, which returns all elements matching the selector.

Wherever a list is implied, such as .each and .length functions, it refers to all the nodes with the name under its parent. E.g.

  1. .select("EmployeeSet > Employee[Name=Amy]") will select first Employee under the EmployeeSet with Name=Amy.
  2. .select("EmployeeSet > Employee[Name=Amy]").length() will first locate the Employee under the EmployeeSet with Name=Amy and then count all Employee nodes following it.

.children(String selector) Will select the first child of the root node matching the selector.

.length() This counts the number of nodes in the parent with the same name.

.text() Returns the text (value) of the node.

.text(String value) Updates the text (value) of the node.

.attr(String name) Returns the attribute value for the named attribute.

.attr(String name, String value) Sets the attribute value for the named attribute.

.delete() Deletes the node.

.append(String xml) The xml is parsed and added as the last child of the node.

.each() Executes an operation on all nodes in the selection. See $Operator above on how to create the anonymous function.
jQuery Java adaptation functions.

OCR and PDF Parsing

server comes with Google's tesseract OCR engine included. The access to OCR features is provided through built-in Java Methods listed above. Tesseract uses an internal XML format to return recognized data from a page. ZOAPIIO uses the same format to work with the OCR API. Additionally, ZOAPIIO provides an API to recognize text from a text PDF file as well. For consistency, the same hypertext format is used for the PDF recognition API as well.

Introduction to HTEXT Format

The HTEXT format contains the details of the text recognized along with the location on the page and the font attributes. A sample is given below-

<div class='ocr_page' id='page_1' title='image ""; bbox 0 0 319 33; ppageno 0'>
   <div class='ocr_carea' id='block_1_1' title="bbox 0 0 319 33">
      <p class='ocr_par' dir='ltr' id='par_1_1' title="bbox 10 13 276 25">
         <span class='ocr_line' id='line_1_1' title="bbox 10 13 276 25; baseline 0 0">
            <span class='ocrx_word' id='word_1_1' title='bbox 10 14 41 25; x_wconf 75' lang='eng' dir='ltr'>
               <strong>the</strong>
            </span>
            <span class='ocrx_word' id='word_1_2' title='bbox 53 13 97 25; x_wconf 84' lang='eng' dir='ltr'>
               <strong>book</strong>
            </span>
            <span class='ocrx_word' id='word_1_3' title='bbox 111 13 129 25; x_wconf 79' lang='eng' dir='ltr'>
               <strong>is</strong>
            </span>
            <span class='ocrx_word' id='word_1_4' title='bbox 143 17 164 25; x_wconf 83' lang='eng' dir='ltr'>
               on
            </span>
            <span class='ocrx_word' id='word_1_5' title='bbox 178 14 209 25; x_wconf 75' lang='eng' dir='ltr'>
               <strong>the</strong>
            </span>
            <span class='ocrx_word' id='word_1_6' title='bbox 223 14 276 25; x_wconf 76' lang='eng' dir='ltr'>
               <strong>table</strong>
            </span> 
         </span>
      </p>
   </div>
</div>
	

Notes on the HTEXT format

  1. The format looks like HTML.
  2. The result is hierarchically broken down into page, para, lines and words.
  3. The title attribute contains the bbox, representing the bounding box of the text location on the input image.
  4. The w_xconf value represents the recognition confidence (0-99).
  5. The dir='ltr' means the text direction is left to right.
  6. The lang attribute is the input text language, 'eng' or English in the example above.

Guided Page Parsing

takes the text recognition from images and PDF documents a step further. Once the HTEXT representation of a page is obtained, an application will typically scan the page and extract relevant parts. This step requires looking at the topology of the page and then breaking the contents into extractions meaningful to the application.

Page Template

The page parsing is done using a page template. In this template you provide a guide to what you are trying to extract from the page. The template is a collection of template items, and each item has the following settings.

Field Description
FieldName This is the name of field and used to identify the extracted value from the output.

LeftFrom LeftFrom and LeftTo (below) together define a vertical band on the page where the field to be extracted lies. The values are in percentages, optional and the default it the full page. For example, to look only in the right half of the page, use values 50, 100.

LeftTo See LeftFrom above.

TopFrom TopFrom and TopTo (below) together define a horizontal band on the page where the field to be extracted lies. The values are in percentages, optional and the default it the full page. For example, to look only in the top half of the page, use values 0, 50.

TopTo See TopFrom above.

Pattern This is a regular expression that the recognized field should match. Please refer to public documentation on Java regular expressions.

ColLabel ColLabel and RowLabel (below) are used to extract fields from a page layout that is tabular in nature. Both these are regular expressions and specify a value for the row heading or the column heading or both for the field.

RowLabel See ColLabel above.
Fields in a template item.

The Page template is a JSON representation of the list of template items. An example is shown below.

[
	{
		"FieldName": "VoucherCode",
		"LeftFrom": "33",
		"LeftTo": "100",
		"TopFrom": "0",
		"TopTo": "0",
		"Pattern": "[A-Z][A-Z0-9]{9}",
		"ColLabel": "",
		"RowLabel": ""
	},
	{
	}
	...
]
	

Page Parsing Result

The page parsing returns two structures, both as JSON formatted arrays - one for all words on the page along with their location on the page and the second with matched words as "Name-Value" pairs.

For both the results strings (JSON), you provide a template each. The template should describe each element of the JS array that you want returned. The template contains placeholders for the substitution values enclosed within two % characters. The following is the list of placeholders.

Result JSON 1

  1. PageH: Page height,
  2. PageW: Page width,
  3. BboxX1: Bounding box coordinate X1,
  4. BboxY1: Bounding box coordinate Y1,
  5. BboxX2: Bounding box coordinate X2,
  6. BboxY2: Bounding box coordinate Y2,
  7. Text: The matched text.

Example Result Template 1

{
	"Text":"%Text%",
	"PageW":%PageW%,
	"PageH":%PageH%,
	"BboxX1":%BboxX1%,
	"BboxY1":%BboxY1%,
	"BboxX2":%BboxX2%,
	"BboxY2":%BboxY2%
}
	

Result JSON 2

  1. Name: The name of the field as in the input template,
  2. Value: The value of the text that was recognized.

Example Result Template 2

{
	"FieldName":"%Name%",
	"FieldValue":"%Value%"
}
	

ZOAPIIO Application Wizard

With the Application Wizard, you can build your fully functional business application in a matter of hours. Refer to the Wizard User Guide for details.

ZOAPIIO Web/Mobile Apps

Building Web/Mobile apps is easy and convenient with . The development is much faster and can be done will minimal programmer skill. The following types of apps are supported-

  1. Classical Web application - ZOAPIIO apps uses HTML5, jQUery and Bulma CSS framework.
  2. PWA - It is based on the classical Web Application with additional feature that it can be installed on a mobile device like an app.
  3. Mobile App - ZOAPIIO mobile apps are built using the cross-platform tool - Flutter, which means the resultant app can run on all mobile platforms including Android and iOS.

Refer to the Front-end Development Guide for details.

Reference Guide

Summary

Tag Description
PRMLCONFIG (Project) The abstraction of your Project.
TYPES Definition of data structures, which can be referenced from the schema.
TAG A data element or structure in the schema - analogous to the XML tag.
SESSION Abstraction of the User Session.
TAG A data element or structure in the schema.
VARIABLES A place to put the global variables in your application. Strictly speaking, you can create program storage anywhere in the schema, but place your transient storage (globals) here for easy reference.
TAG A data element or structure in the schema.
COOKIES Abstraction of HTTP Cookies.
TAG A data element or structure in the schema.
REQUEST Abstraction of the HTTP Request. Although not a requirement, you should declare the incoming query variables and POST data definitions here.
TAG A data element or structure in the schema.
HTTP-HEADER Abstraction of HTTP headers in the Request.
TAG A data element or structure in the schema.
TAG Because the schema is hierarchical, the TAGs can be nested to an arbitrary depth.
ATTRIBUTE Analogous to the XML TAG attribute. If you are using JSON based request/response, do not use Attribute because JSON has no equivalent construct.
ATTRIBUTE-GROUP A mechanism to reuse Attribute definitions from a TAG defined under TYPES.
PROPERTY-SET Abstraction of Application Properties stored on the server.
DATABASE-TABLE Abstraction of a Relational database table.
TAG TAG under the Database Table represent table columns and cannot be nested.
DATABASE-QUERY TAG under the Database Table represent table columns and cannot be nested.
TAG TAG under the Database Query represent columns in the Query result set.
QUERY-PARAMETER Database queries can have parameters.
MONGO-COLLECTION Abstraction of the MongoDB.
QUERY-PARAMETER Mongo DB access can have query parameters.
EMAIL-SENDER Abstraction of SMTP. Allows as access point for sending out Emails.
TRANSFORMATIONS All your processing logic is defined under this node.
DECLARATIONS The Java entry point to your project. This is automatically generated and for most cases, you will not need to change it.
ENTRY-POINT Abstraction of the HTTP entry point.
ENTRY-POINT-SOAP Abstraction of the SOAP entry point.
SOAP-ACTION SOAP services allow multiple Actions on the same entry point (URL).
ENTRY-POINT-GRAPHQL Abstraction of the GraphQL entry point.
GRAPHQL-QUERY A GraphQL Query (read as well as update).
ENTRY-POINT-JMS Abstraction of the MQ or JMS entry point.
ENTRY-POINT-EMAIL Abstraction of the Email listener.
ENTRY-POINT-WEBSOCKET Abstraction of the Web-Socket entry point.
ENTRY-POINT-PROCLET Proclets are processes (routines) with a URL. They cannot be called from outside but are accessible to all projects in your instance.
METHOD Method is a Java function - used to implement low-level and complex tasks.
ROUTINE Routine is a reusable piece of ZOAPIIO program. Can be called from your project only.
XSLT XSL Transformation interface. You can use XSLT in your ZOAPIIO programs.
XML-STUB A way to include fixed XML stubs in your application for easy initialization of nodes at runtime.
WEB-SERVICE Abstraction of an outgoing Service API (SOAP as well as HTTP).
HTTP-HEADER HTTP headers for use in the Web Service.
SOAP-HEADER SOAP headers for use in the (SOAP) Web Service.
MQ-DESTINATION Abstraction of an MQ (JMS) to which messages can be sent.
WEB-SCRAPER ZOAPIIO supports Selenium driven Web Scraping. This is the abstraction of a Web-Scraper.
WEB-APPLICATION Refer to the Front-end Development Guide for details. .
APP-COMMONS

Statements (ZOAPIIO Programming) // (Comment), Abort, Break, Compute, Call, Continue, Database, Declare, DbQuery, Execute, Execute2, ExportXml, ForEach, if, Java, JmsSend, Mongo, Node, NodeCopy, NodeInit, Proclet, Return, Sleep, WebScrape, WebSocketGet, WebSocketSend, While, With, WsCall, WsControl, WsSyncCall, Xslt,
ZOAPIIO WebIDE schema.

ATTRIBUTE

"ATTRIBUTE"s apply to a TAG and represents an XML attribute of the TAG. It is useful only when dealing with XML messages - they have no equivalent in JSON, so if your messages are in JSON format, you should avoid these.

Attribute Seq Description
Name 1 The name of the attribute, must follow naming rules of XML attributes.

Data Type 2 The Data type of the attribute. XML captures all attributes as strings, but if you want to the ATTRIBUTE values in expressions, you should declare a data type.

Size 3 This is usually ignored, and you can safely leave it blank. It represents the maximum length this attribute can have. System does not perform any validation at runtime and is for documentation only.

Description 4 Textual description of the purpose of the attribute and what the contents mean. It is for documentation purposes.
Attributes of the "ATTRIBUTE" Tag.

ATTRIBUTE-GROUP

"ATTRIBUTE-GROUP"s apply to a TAG and is a mechanism to have reusable ATTRIBUTE groups. You can create an ATTRIBUTE-GROUP and put attributes under it or simply refer to a TAG under TYPES whose attributes are being referred.

Attribute Seq Description
Ref 1 The name of the Attribute group (TAG under TYPES) that is being referred.

Description 2 Textual description for documentation purposes.
Attributes of the "ATTRIBUTE-GROUP" Tag.

COOKIES

"COOKIES" is a TAG for definition of HTTP cookies. TAGs defined under this node are treated as cookies. You can access the value of a cooking through the cookie TAG for read as well as update.

Attribute Seq Description
Description 1 Textual description for documentation purposes.
Attributes of the "COOKIES" Tag.

DATABASE-QUERY

"DATABASE-QUERY"s offers a means of executing SQL queries on the Database. If the standard read, update operations available on the Database tables do not meet your requirements, you can write direct SQL queries and execute them. See Using Queries.

Attribute Seq Description
Database Name 1 The database on which the query should be run.

Is Update 2 A flag to indicate that this is an update query. You must check this flag to match the nature of the query, otherwise the query will fail.

Query Name 3 Give a name to the query, using which it will be referred inside your programs (Web-API logic).

SQL 4 The SQL statement for the query. The knowledge of SQL is required, and it must be syntactically correct. The SQL statement can have substitution parameters, which are inserted at run-time. See QUERY-PARAMETER. Inside the SQL statement use &1, &2.. etc. to refer to substitution parameters and then declare the parameters under the DATABASE-QUERY Tag. The order of QUERY-PARAMETER declaration is important because these are positional parameters.

Description 5 Textual description for documentation purposes.
Attributes of the "DATABASE-QUERY" Tag.

DATABASE-TABLE

"DATABASE-TABLE"s offers a means of accessing your database tables for read and update.

Attribute Seq Description
Database Name 1 The database on which the table exists.

Table Name 2 The name of the Database table. If the name has a hyphen (-) in its name, it is automatically replaced with the underscore (_) before performing database operations because hyphen is not a valid character in Relational database table names.
Attributes of the "DATABASE-TABLE" Tag.

DECLARATIONS

, internally, wraps your project in a Java class and compiles it before deploying it in your application container (Instance). "DECLARATIONS" Tag contains the class declaration, and in most cases, you should leave it alone. The reason it is exposed to the Web-API builder is that in advanced situations, you may need more control on how the class is compiled. If you are using Java Methods in your project -

  1. You may want to import Java libraries in your class. Using import in Java is optional and your Java code can use fully qualified class names, so more importantly-
  2. You may want to declare common Java functions that you can access across the project. You will add those functions in the DECLARATIONS section.
  3. Important note: You should not declare any instance variables in the class. Your container creates only one object for the Web-API class and all service instances run inside the same object. Any instance variables will be shared by all the services and will create conflicts in their operation.
  4. Your services will require local storage - you should create Tags under /VARIABLES and use those for local storage.

Attribute Seq Description
Type 1 Must be 'Java'. No other programming language is supported.

Description 2 Textual description for documentation purposes.
Attributes of the "DECLARATIONS" Tag.

ENTRY-POINT

"ENTRY-POINT" node in your schema declares a REST Web-API that your project is providing. To declare Web-APIs that your project is consuming, see WEB-SERVICE. The entry point is attached to a URL. The public URL of the Web-API is constructed by prefixing your dedicated container URL to the URL you specify here. (The URL of your container is- "https://my.zoapiio.com/{your instance code}". You can get your instance code from the account panel, where you signed up. It is also visible in the URL of the Web-IDE page.)

Query Parameters

HTTP protocol allows data (parameters) to be passed with a request as a query string in the URL or as a part of the POST body. When the Web-API starts executing, will extract the input data coming with the request and present it to your program in the Data tree.

  1. The input parameters that your API is expecting should be declared in your schema. Any input coming in that is not declared is thrown away.
  2. Conventional query string parameters are received as single field values.
  3. Two special query parameters are recognized "_XML" and "_JSON". Any data coming in these query parameters is treated as complex structure (In XML and JSON format respectively) and the contents are unfolded.
  4. The REST API's typically do not use query parameters and send the input data in XML or JSON format in the POST body. If your input in coming as POST body, you must declare it in ENTRY-POINT properties, so it can be handled.
  5. Please note that any client sending complex structures as POST data should also send the appropriate HTTP header value for "Content-Type" - such as "application/xml" or "application/json".
Path Parameters

In REST API's it is a common practice to pass additional parameters within the URL path itself. E.g. to get the details of an Employee with a known id, the conventional URL would look something like https://.../wc/getEmployee?Id=M100, but using Path parameters, the same URL becomes https://..../wc/getEmployee/M100.

To handle this in , you will declare the ENTRY-POINT with URL /wc/getEmployee. will map all requests which have '/wc/getEmployee/' as prefix to the same entry point. The path components following the base URL can be accessed in your program using Data path /REQUEST@_PATH1, /REQUEST@_PATH2 etc.

Attribute Seq Description
URL Path 1 The path on which the Web-API would be called. mandates that this always start with "/wc/".

Response Type 2 The format in which the Web-API's output should be returned. The contents of the Response Path are automatically serialized in the format and sent back to the caller. Possible values are - JSON, XML, TEXT, or B64-BINARY (Used for binary data). XML and JSON cannot handle binary data and any binary data is usually held in a standard format called Base64, which converts binary strings to text. If you set the Response Type to B64-BINARY, then will treat the output of the Web-API as a Base64 encoded text string and will send the equivalent binary data to the caller.

Request Path 3 This is the Path of an element in the schema, where you want the input data to be extracted. It defaults to "/REQUEST".

Response Path 4 The Path from where the output of the Web-API will be taken by .

Allowed OAuth User List 5 If this field is left blank, will not apply any user authentication on the incoming requests. You must set this to the list of users who are permitted to access this service, for to apply OAuth validations. You should set this field to "*" if you want the security to be enabled and all configured users to be granted access. See Web-API Security.

Allowed Origin IP List 6 Another way to restrict access to the API is by IP address. You can specify the list of white-listed IPs here, to activate the IP checking on the API.

Trace Logger 7 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Timeout (Seconds) 8 You can specify a timeout value with your API. If the service does not finish execution during this time, it is interrupted.

Content Type (If TEXT) 9 If the Response Type of your API is "TEXT", you can provide a content type (Content-Type HTTP header) to let the callers know what the data contains.

Content Disposition (If TEXT) 10 Like Content Type, but for the Content-Disposition HTTP header.

Description 11 Textual description for documentation purposes.
Attributes of the "ENTRY-POINT" Tag.

ENTRY-POINT-EMAIL

"ENTRY-POINT-EMAIL" node in your schema declares a processor for the EMAIL Message. The entry point does not have a URL because it is never explicitly called. It is attached to an Email account (configured on the server) and is automatically invoked when an Email arrives on that account.

The Email message is passed to the handler as an object of class javax.mail.internet.MimeMessage, and you will be required to write a Java method in your project to extract the parts of the message. Inside the method, you should use MimeMessage mm=(MimeMessage)getEmailMessage("/"); to gain access to the message. From the entry point code, you should call your Java Method, extract required information and store it in your schema tree. The remaining part of the processing, such as updating the database, can continue from the entry point code.

Attribute Seq Description
Email Endpoint 1 The Email Account which this service is serving. Choose from the list of pre-configured Accounts. If you do not see any value in the selection, this means none has been configured and you should contact your system administrator.

Trace Logger 2 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Is Active 3 Indicates if the handler is active.

Description 4 Textual description for documentation purposes.
Attributes of the "ENTRY-POINT-EMAIL" Tag.

ENTRY-POINT-GRAPHQL

"ENTRY-POINT-GRAPHQL" node in your schema declares a processor for the GraphQL Query. GraphQL Queries, which run on the same URL should be declared under this node (See GRAPHQL-QUERY below). Both Query and Mutation types are supported.

Attribute Seq Description
URL Path 1 The path on which the GraphQL Web-API would be called. mandates that this always start with "/gq/".

Allowed OAuth User List 2 If this field is left blank, will not apply any user authentication on the incoming requests. You must set this to the list of users who are permitted to access this service, for to apply OAuth validations. You should set this field to "*" if you want the security to be enabled and all configured users to be granted access. See Web-API Security.

Allowed Origin IP List 3 Another way to restrict access to the API is by IP address. You can specify the list of white-listed IPs here, to activate the IP checking on the API.

Trace Logger 4 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Timeout (Seconds) 5 You can specify a timeout value with your API. If the service does not finish execution during this time, it is interrupted.

Description 6 Textual description for documentation purposes.
Attributes of the "ENTRY-POINT-GRAPHQL" Tag.

ENTRY-POINT-JMS

"ENTRY-POINT-JMS" node in your schema declares a processor for the JMS Message Queue (MQ). Like the REST Entry point is attached to a URL, the JMS entry point is attached to a Queue. Your instance comes with two pre-configured JMS endpoints (one topic and one queue).

Attribute Seq Description
JMS Endpoint 1 The JMS Endpoint which this service is serving. Choose from the list of pre-configured JMS Endpoints.

Request Type 2 The type of input request - JSON, XML or TEXT.

Request Path 3 This is the Path of an element in the schema, where you want the input data to be extracted.

Service Threads 4 The number of service threads that should be used. If the processing is simple and quick, you should assign just one thread. However, if the processing is time consuming, you may pick a higher number such that the overall load is managed without chocking the hardware resources. If you select a low number, the queue may build up and processing will lag behind and a high number might overload your hardware.

Trace Logger 5 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Is Active 6 It is possible to attach multiple services to a JMS Endpoint. Generally, the MQ environments are used in high-traffic situation, so multiple processors are common. You can activate/deactivate JMS services using this flag.

Description 7 Textual description for documentation purposes.
Attributes of the "ENTRY-POINT-JMS" Tag.

ENTRY-POINT-SOAP

"ENTRY-POINT-SOAP" node in your schema declares a SOAP Web-API that your project is providing. To declare Web-APIs that your project is consuming, see WEB-SERVICE. The entry point is attached to an URL. The public URL of the Web-API is constructed by prefixing your dedicated container URL to the URL you specify here. (The URL of your container is- "https://my.zoapiio.com/{your instance code}". You can get your instance code from the account panel, where you signed up. It is also visible in the URL of the Web-IDE page.)

SOAP services allow for multiple SOAP actions within the same service. So the same URL can service multiple related functions. The actual service is declared within the SOAP-ACTION node.

Attribute Seq Description
URL Path 1 The path on which the SOAP service would be called. mandates that this always start with "/ws/".

XML Namespace 2 XML uses the concept of namespace to keep same tag names in messages of different providers from conflicting. It is an advanced subject, and in most cases, you can leave this blank. If provided, it should be a fully qualified URL that is unique to your organization. E.g., https://yourdomain.com/zoapiio-api.

Trace Logger 3 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Timeout (Seconds) 4 You can specify a timeout value with your API. If the service does not finish execution during this time, it is interrupted.

Description 5 Textual description for documentation purposes.
Attributes of the "ENTRY-POINT-SOAP" Tag.

ENTRY-POINT-WEBSOCKET

"ENTRY-POINT-WEBSOCKET" node in your schema represents a processor for the Web-Socket. The entry point is attached to a URL.

Attribute Seq Description
URL Path 1 The path on which the Web-Socket will serve. mandates that this always start with "/wt/".

Allowed OAuth User List 2 If this field is left blank, will not apply any user authentication on the incoming requests. You must set this to the list of users who are permitted to access this service, for to apply OAuth validations. You should set this field to "*" if you want the security to be enabled and all configured users to be granted access. See Web-API Security.

Allowed Origin IP List 3 Another way to restrict access to the API is by IP address. You can specify the list of white-listed IPs here, to activate the IP checking on the API.

Trace Logger 4 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Description 5 Textual description for documentation purposes.
Attributes of the "ENTRY-POINT-WEBSOCKET" Tag.

GRAPHQL-QUERY

"GRAPHQL-QUERY" node in your schema represents a Query under the ENTRY-POINT-GRAPHQL. Multiple Queries can be serviced on the same URL. You can add any number of Query or Mutation type Queries under the entry point.

Attribute Seq Description
Query Name 1 The name of the query. This name is present in the incoming GraphQL request and is associated to this Query through name.

Arguments Path 2 The Data path where incoming arguments will be extracted. Note that there is no default, and a Path must be provided.

Response Message Path 3 The Data path from where the response message will be produced - the contents are automatically formatted as specified in GraphQL request and rendered.

Is Mutation 4 Check this if the Query is a mutation query.

Trace Logger (Override) 5 The name of the logger for this query, if you want it to be different from the entry point logger

Description 6 Textual description for documentation purposes.
Attributes of the "GRAPHQL-QUERY" Tag.

HTTP-HEADER

"HTTP-HEADER" node represents an HTTP header with a Web Service that you are consuming. If you need to send a specific HTTP header to that service, you should declare it here and then assign it a value before calling the web service.

Attribute Seq Description
Name 1 The name of the HTTP header. E.g., Content-Type.

Description 2 Textual description for documentation purposes.
Attributes of the "HTTP-HEADER" Tag.

METHOD

"METHOD" node represents a callable routine in Java programming language. You can write any processing you need to do in Java as METHODs. For details, see Java method. If you have declared common Java functions under DECLARATIONS section, they can be directly called from your Java METHODs. The METHOD prototype declaration is fixed - it receives two Node objects (passed at the time of calling) - in and out. Despite the suggestion the variable names make, both behave identically, and you can read as well as update both.

Also important to note that the Node objects should not be manipulated using Java DOM methods, the inherited functions, get() and set() should be used instead.

Attribute Seq Description
Method Name 1 The name of the METHOD by which it will be referenced in your programs.

Method Type 2 Must be 'Java' - no other language is supported.

Synchronized 3 This is a mechanism used to manage synchronization between two different METHODs in your program. Any arbitrary token can be specified here and any two METHODs that have the same synchronization token, will never enter execution simultaneously. If one is already executing, the others will wait until it finishes, and each will execute in turn. This is an advanced subject, and chances are you will never need to use this feature.

Description 4 Textual description for documentation purposes.
Attributes of the "METHOD" Tag.

MQ-DESTINATION

"MQ-DESTINATION" node represents a JMS Message Queue or Topic to which your project needs to send messages.

Attribute Seq Description
MQ Destination Name 1 The name of the MQ destination by which it will be referenced in your programs.

JMS Server 2 The Message Queue or Topic that is configured in your instance. Pick a name from the drop-down list.

Description 3 Textual description for documentation purposes.
Attributes of the "MQ-DESTINATION" Tag.

PROPERTY-SET

"PROPERTY-SET" node represents a way of accessing your Application Properties. Add a PROPERTY-SET Tag in your Schema to gain access to the property set.

Attribute Seq Description
Name 1 The name of the Property set (select from drop-down) - your application comes pre-configured with a property set.

Description 2 Textual description for documentation purposes.
Attributes of the "PROPERTY-SET" Tag.

QUERY-PARAMETER

"QUERY-PARAMETER" Tag is used in DATABASE-QUERY to pass values to parameters used in the Query. Parameters should be declared in the same order as they appear in the query string. See Using Queries.

Attribute Seq Description
Name 1 The name of the Query Parameter, by which you will reference it in your program.

Data Type 2 The Data type of the parameter - pick from the drop-down.

Replace Inline 3 If this field is checked, then will make the substitution in the query string before passing it to the SQL execution engine. By default, the Query string and parameters are separately passed to the SQL engine. Inline substitution allows you to substitute even keywords within the Query, while SQL engine substitution works only for values appearing the Query string.

Description 4 Textual description for documentation purposes.
Attributes of the "QUERY-PARAMETER" Tag.

REQUEST

"REQUEST" is a TAG that represents (abstracts) the HTTP Request associated with REST Web-APIs.

Attribute Seq Description
Description 1 Textual description for documentation purposes.
Attributes of the "REQUEST" Tag.

ROUTINE

Good programming practice requires that you imagine your overall business functionality as smaller independent sub-processes, which can be implemented without too much complexity - the programmer's "Divide and Rule" principle. While it helps contain complexity, its main purpose is to allow the sub-routines to be called multiple times using parameters. For example, the functionality to lookup an Employee's salary from its Id would be implemented as a routine, which receives Employee Id as parameter. Then this sub-routine can be used from multiple places from your project, wherever this lookup is required.

"ROUTINE" TAG lets you do this, and it declares a callable sub-routine. Each ROUTINE has two parameters (passed at the time of calling) both of which are nodes from the Data tree. These parameters are called Input, and Output - although there is no restriction on updating or reading any of these inside the routine. Inside the routine two special Data paths - /_IN, and /_OUT are used to access the nodes respectively.

Attribute Seq Description
Name 1 The name of the Routine, by which you will reference it in your program.

Parameter -Input 2 This should be an absolute path to represent the type of Input parameter. The actual parameter passed while calling can be different, but it should be of same Data type as this one. This is needed so that the Logic Builder can validate the Data path names that you use in your routines. E.g., a Data path /_IN/Name can only be validated if the type of incoming parameter is known.

Parameter -Output 3 Same as above, but for the second (Output) parameter.

Description 4 Textual description for documentation purposes.
Attributes of the "ROUTINE" Tag.

SESSION

Sessions are used by Application programs to remember the identity of the users. In a web-based application, this is done through HTTP cookies. takes ownership of managing the session for your application. The "SESSION" Tag represents the User session - you can freely add or change information to the Data tree under the SESSION and will preserve its contents across calls.

Typically, you will populate the user details in the session when the user logs on and then every Web-API in the same session (same Cookie) can access that information.

Attribute Seq Description
Link to Cookie 1 The name of the Cookie, using which the Session would be tracked. You need to separately create a Cookie by the same name under the COOKIES Tag.

Storage 2 Presently only "Database" option is available, and you can select that.

Database Name 3 Database where the session information would be stored. This should be the default database configured for your instance.

Description 4 Textual description for documentation purposes.
Attributes of the "SESSION" Tag.

SOAP-ACTION

Your SOAP entry points will have SOAP actions. SOAP-ACTION is an action that can be invoked on the same URL but with a SOAP action option passed to it. runtime matches the Root name in the incoming SOAP (XML) message and selects the right SOAP action to execute.

Attribute Seq Description
Name 1 Even though the SOAP action is automatically selected by the runtime, you must provide a name to identify the SOAP action. If two SOAP actions have the same root name, then the additional SOAP action is expected to exactly identify the action to execute.

Request Message Path 2 The Data path where incoming message will be extracted. Note that there is no default, and a Path must be provided. The /REQUEST default only apply to REST entry points.

Response Message Path 3 The Data path from where the response message will be taken - the contents are automatically formatted as SOAP message format and replied.

SOAP Header Path 4 The Data path into which the SOAP header would be extracted from the input message.

XML Namespace 5 The XML namespace for the response message.

Trace Logger 6 The name of the logger where the execution trace should be printed. You can leave this field blank to disable trace logging.

Description 7 Textual description for documentation purposes.
Attributes of the "SOAP-ACTION" Tag.

SOAP-HEADER

SOAP headers are like HTTP headers, except they apply to only SOAP messages and carry specific SOAP control information. The "SOAP-HEADER" Tag is used to pass SOAP headers to web-services being consumed in your program.

Attribute Seq Description
Name 1 The name of the SOAP header.

XML Namespace 2 The XML namespace for the SOAP header.

Description 3 Textual description for documentation purposes.
Attributes of the "SOAP-HEADER" Tag.

TAG

"TAG" Tags form the bulk of your schema because they represent the data elements in your Data tree. The attributes of the TAG change depending upon where it is declared. E.g., the properties of TAG appearing in the DB Table definition would be different from the ones appearing in the rest of the Data tree.

Attribute Seq Description
Name 1 The name of the TAG. This is the name by which it would be referenced in your program and also it will take the same name when serialized into XML or JSON.

Data Type 2 The Data type of the TAG is important because the expression evaluator consults the data type when performing operations. In not specified, STRING is assumed, and for group level TAGs, it is ignored. Pick from the drop down or use "TYP:", "REF:", or "EXT:" notation to refer to other structure declared in your schema. See Data Types.

Size 3 The Size attribute is ignored and is generally to document the maximum size this TAG can have. No validations are performed, however.

Key Component 4 This Key component flag is relevant when the parent TAG is declared to have duplicates. See Indexes and Keys for details.

Required 5 This setting is also ignored and is used to document whether this TAG is mandatory to be present in incoming or outgoing messages.

Duplicates 6 Specifies whether multiple instances of this TAG are permissible in the Data tree. enforces this constraint and will not allow duplicates where this flag is not checked. Another impact of this flag is on how a node is serialized into JSON. A Tag will "Duplicates" checked will be rendered as an array.

XML Namespace 7 Applicable for XML messages and overrides the values of the parent Tag, if any. Most of the time, it can be left blank.

Description 8 Textual description for documentation purposes.
Attributes of the "TAG" Tag.

TRANSFORMATIONS (Business Flows)

A Node in your schema, where you put all your processing related Tags.

Attribute Seq Description
Description 1 Textual description for documentation purposes.
Attributes of the "TRANSFORMATIONS" Tag.

TYPES

"TYPES" is the Node in your schema, where you put all your reusable structure definitions. The data structures declared here do not become a part of the schema, but they are only declarations. TAGs must be separately declared in the schema and refer to the data types here. See Data Types.

VARIABLES

Programs require temporary storage - In , "VARIABLES" Tag is where you will declare your global storage for your project. Please note that the contents of the entire Data tree, including VARIABLES, is accessible across your project. Each service invocation, however, has its own separate Data tree.

Attribute Seq Description
Description 1 Textual description for documentation purposes.
Attributes of the "TYPES" Tag.

WEB-SERVICE

"WEB-SERVICE" Tag declares a Web-API (or Web service) that your project will consume. The service can be a service within your project or an external service on the Web.

Attribute Seq Description
Web Service Name 1 The name of the web-service, by which it will be referenced in your program.

URL to Call 2 The URL to call the web-service. This should be a fully qualified URL (starting with (http://, or https://) for external services. For services local to your instance, you can enter the relative URL (starting with / - as defined in the entry point).

A special notation is permitted which allows the URL to be picked up from the property set. Use '@' character following by the full Data path of the property setting. E.g., @/MainProps/myservice_url. The value of the application property will be used as the URL.

Service Type 3

What type of service it is - select from the drop-down. SOAP or HTTP (PUT, GET, POST, PATCH).

There are certain subtle nuances to calling HTTP services, all of which cannot be abstracted through the definition here. implementation would cover almost all situations, but you may still encounter exceptions that are not handled by this implementation.

A special option here - "POST as GET" - is used to manage one such exception. HTTP specification says that a GET request cannot have a request body - however in practice, it is not strictly barred. The POST as GET option allows you to format your request like a normat POST request, but system submits it using the GET method.

Internally, handles such exceptions, including this one, by invoking the request using the shell command - curl. Curl is a powerful command to invoke HTTP(s) requests and would certainly allow you to handle more exception situations. You can have use curl to invoke the HTTP requests and specify additional command line options. See next two options below.


Invoke via 'curl' 4

Check this box if you have an exception situation that cannot be expressed within the definition but can be handled by some 'curl' command line options.

Using this option will cause the 'curl' command to be invoked at run-time, which has an obvious, though small, processing overhead. You should be aware of this when using this option.


Curl Options 5

When choosing to use curl for request invocation, specify the command line options here - these will be added to the command at the time of invocation. @ reference can be used for this value - meaning it can be linked to a Property value or any other element in the schema. E.g. @/MainProps/CurlOptions will pick the value at run-time from the given path.

Another way to override this value at run-time is by assigning a value to [ServiceName]@_CURLOPTIONS before calling the service.


SOAP Action 6 If the service is a SOAP service, you can specify a SOAP Action value.

Request Type 7 When calling an HTTP service, you can specify how the data should be sent.
  1. Individual Values: The values are sent as query string, each value separately - this can be used if you have few parameters.
  2. Serialized XML: This will serialize the data as XML and send it as a single Query parameter by the name "_XML".
  3. JSON: The input is rendered as JSON and sent as the body of the request. This cannot be used with GET.
  4. XML: The input is rendered as XML and sent as the body of the request. This cannot be used with GET.
  5. Raw: The input (must be formatted by the application) will be sent as the body of the request. This cannot be used with GET.

Content Type (Raw) 8 When using 'Raw' in Request Type, you should specify a value for Content-Type HTTP header, so the called service knows how to interpret the data.

Response Type (HTTP) 9 For HTTP services, provide the type of response to expect. Possible values - XML, JSON, STRING or BINARY. If set to Binary, the response is read and base64 encoded for XML compatibility.

Use Compression 10 You can control the type of compression to be used in calling this service. Possible values - gzip, deflate, or none. Unless the Web-service does not support compression, it is recommended to use a form of compression - gzip is the most commonly used compression.

XML Namespace 11 When sending XML data, you can use a namespace value.

Username 12 This attribute is obsolete now and was used earlier to include username and password information in the URL itself. Still, if you are calling an older service that still this form of authentication, you can specify the username and password here.

Password 13 See Username above.

Description 14 Textual description for documentation purposes.
Attributes of the "WEB-SERVICE" Tag.

WEB-SCRAPER

"WEB-SCRAPER" Tag declares a Website that your project will scrape.

Attribute Seq Description
Web Scraper Name 1 The name of the web-scraper, by which it will be referenced in your program.

Scraper Pool 2 ZOAPIIO allows multiple configurations for scraping, to get the widest coverage. Your system administrator will configure different pools for each configuration that will inform you of the capabilities of each pool. Pick the one that is suitable for your needs.

Opening URL 3 The URL of the website being scraped. This can be overridden in your program before opening the scraper by setting the URL value in /{ScraperName}@_URL.

Scraper Agent 4 Pick a scraping agent (browser) from the list - firefox, chrome, phantomjs, headless. The agent must be supported by the pool you have selected, and the version of the browser is fixed by the pool.

Alternate Agent 5 Same as Scraper Agent above - an alternate to use if the main agent is not supported by the pool.

Load Images 6 Boolean value to disable loading of images when scraping. This feature may not be available in all Scraping Agents.

Load CSS 7 Boolean value to disable loading of CSS when scraping. This feature may not be available in all Scraping Agents.

Run Headless 8 Some Scraping Agents allow headless invocation. Use this checkbox to use headless mode. This is different from the headless scraping agent, which is an altogether different scraping agent.

New Window Handling 9 The scraping script execution, at some point, may open a new window. This creates complexity in scraping because window management becomes a task. ZOAPIIO scraper allows window switching, but if possible, it is easier to either ignore (disallow) if not important or force the new window to open in the same window as parent.

Options are - 'Disallow' and 'Open in the same Window'. Please note that this is not always possible or desirable.

UserAgent String 10 UserAgent string is used by the browser to identify itself and the environment. Very rarely, but sometimes, the site behaviour changes based on the value of this. You may specify a UserAgent string of choice, if needed.

Debug Mode 11 Internal use.

Emulation Mode 12 Options are "none" or "human". If human is selected, the data entry into the browser elements is slowed to appear as if a human is typing it.

Description 13 Textual description for documentation purposes.
Attributes of the "WEB-SERVICE" Tag.

XML-STUB

"XML-STUB" Tag declares an inline XML document, which can be used to initialize parts of outgoing messages without needing to initialize it element by element.

Attribute Seq Description
Name 1 Name of the XML-STUB by which it will be referenced in your program.

Type 2 Must be 'Xml' - select it from the drop-down.

Description 3 Textual description for documentation purposes.
Attributes of the "XML-STUB" Tag.

XSLT

"XSLT" Tag declares an inline XSLT script (program), which can be used to apply transformations within the Data tree. This is for advanced use and requires the knowledge of XSLT programming.

Attribute Seq Description
XSLT Name 1 Name of the XML-STUB by which it will be references in your program.

Type 2 Must be 'Xslt' - select it from the drop-down.

Description 3 Textual description for documentation purposes.
Attributes of the "XSLT" Tag.

Statements

Statements in your program follow a common structure. Each statement has a name and up to four parameters - not all parameters are mandatory. The parameters appear in a fixed sequence. Your Web-IDE Logic Builder, manages the parameters for you -

  1. Where possible a drop-down is presented for selection
  2. Data paths can be dragged from the Schema window into a position that expects a Data path.
  3. Free input text like Data paths and expressions are validated, where possible.
  4. The Logic builder will ensure the integrity of the program structure allowing only syntactically valid connections.
  5. Some statements appear as blocks in the Logic builder because they represent compound statements - like conditions and iterations.

// (Comment)

Comments are used to improve the readability of your program. You should insert comments to describe what you are doing - it is not always obvious from reading the program alone.

Parameter Seq Description
Comment Text 1 Free text.
The Comment statement.

Abort

The "Abort" statement causes the presently executing service to return immediately. It does not imply that the service has failed - it is to be viewed as a return from the service. The response message is rendered normally - the caller does not see any error. An optional condition can be specified, if the "Abort" action is conditional.

Parameter Seq Description
Test (Expression) block 1 This is an optional parameter. If specified, the Abort action is taken only if the expression evaluates to true.
The Abort statement.

Break

The "Break" statement is same as the break statement in most programming languages. It can be used only inside an iteration block. It causes the iteration to be exited immediately and the control resumes at the statement following the iteration block. If there are multiple nested iteration blocks, this will exit from the innermost block only. An optional condition can be specified, if the "Break" action is conditional.

Parameter Seq Description
Test (Expression) block 1 This is an optional parameter. If specified, the Break action is taken only if the expression evaluates to true.
The Break statement.

Compute

The "Compute" statement evaluates an expression. It is the most used statement, and its most common use is to copy values around the Data tree (using the assignment operator).

There are other more compact ways of copying values in and if you find yourself using too much of "Compute" for copying values, see if "NodeInit" or "NodeCopy" can work for you.

Parameter Seq Description
Expression 1 This is a free text field but must be a syntactically valid expression - your Web-IDE performs validation and flags error if any. Please note that on an invalid expression, Web-IDE only issues a warning, but you must make sure the expressions are valid for them to execute correctly at runtime.
The Compute statement.

Call

The "Call" statement is used to call a Java method. Up to two parameters - both nodes - can be passed to the call. By nomenclature, they are referred to as in and out, although there is no restriction on their use and treatment.

Parameter Seq Description
In (Data path) 1 The first parameter to the Method - this is optional, if provided the Data path must point to an existing node in the Data tree.

Out (Data path) 2 The second parameter to the Method - this is optional, if provided and the Data path does not point to an existing node in the Data tree, an empty node is automatically created.
The Call statement.

Continue

The "Continue" statement is same as the continue statement in most programming languages. It can be used only inside an iteration block. It causes the execution to skip the remainder of processing in the current block and proceed with the next iteration. If there are multiple nested iteration blocks, this will apply to the innermost block only. An optional condition can be specified, if the "Continue" action is conditional.

Parameter Seq Description
Test (Expression) block 1 This is an optional parameter. If specified, the Continue action is taken only if the expression evaluates to true.
The Continue statement.

Database

The "Database" statement is used to invoke various operations on a Database Table.

Parameter Seq Description
Operation (Drop-down) 1 The database operation to perform. See DB operations below.

Table name (Drop-down) 2 The Table on which the operation is performed.
The Database statement.

DB Operations

All DB operations communicate the success status through the Pseudo element /_STATUS under the table name. If you want to check if the operation succeeded, a non-zero value indicates a failure. E.g., /Employee/_STATUS will contain the success status of operations on the table Employee.

Operation Description
fetch It fetches a single row from the table. The Table must have unique key (or key combination) defined, and prior to calling this operation the values must be assigned to the Key columns. This operation will fetch the row corresponding to the specified key.

open It opens a result set on the Table containing multiple rows and fetches the first row from the set. After this operation, you will typically iterate over the results using the "ForEach" iteration statement. Before calling this operation, a value must be assigned to the pseudo /_WHERE element containing the syntactically correct WHERE portion of an SQL statement. E.g., /Employee/_WHERE = "EmployeeId = 'M100' or EmployeeStatus = 0" (assuming EmployeeId and EmployeeStatus are columns in the Table).

The open operation can be skipped, when using ForEach iteration with a Where expression. See ForEach description above.

next This operation advances to the next row in a result set. You do not need to call this operation, if using "ForEach" (it automatically does that for you) to access the results.

close This operation should be called after you are finished processing the result set obtained using the "open" operation. This can be omitted when using ForEach iteration with a Where expression. See ForEach description above.

save This operation saves a row in the database. If a row has been fetched using "open" or "fetch", the same row is updated (using the key value), otherwise a new row is inserted.

insert This is like "save", except it always forces an insert of a new row.

delete Deletes a single row from the Table based on the key value. If a row has been previously fetched, it will use the key for that row, otherwise you manually assign values to the key columns and then call this operation to delete the row.

clear Deletes multiple rows from the Database Table. Before calling this operation, a value should be assigned to the /_WHERE pseudo element, which is used as the selection for rows to be deleted.
Database operations.

Declare

Declare is used to define a local variable. The declaration feature is only available inside a ROUTINE. Local variables are accessed using the path /_LOCALS/{Name}. It has a scope local to the current execution frame in the execution stack.

supports recursion - a ROUTINE can call itself with a new set of parameters. Each execution frame gets its own reference to /_IN, /_OUT and /_LOCALS nodes. When the ROUTINE returns the previous frame is restored.

Parameter Seq Description
Name 1 The name of the variable - Node naming rules apply.

Data type 2 The data type of the variable. The variables are elementary data types and nested structures cannot be declared.
Duplicates 3 Whether the variable supports duplicates.
The Declare statement.

DbQuery

The "DbQuery" statement is used to invoke various operations on a Database Query (DATABASE-QUERY).

Parameter Seq Description
Operation (Drop-down) 1 The query operation to perform. See Query operations below.

Query name (Drop-down) 2 The Database Query on which the operation is performed.
The DbQuery statement.

Query Operations

All Query operations communicate the success status through the Pseudo element /_STATUS under the query name. If you want to check if the operation succeeded, a non-zero value indicates a failure. E.g., /EmployeeQ/_STATUS will contain the success status of operations on the query EmployeeQ.

Operation Description
open It opens a result set on the Database Query containing multiple rows and fetches the first row from the set. After this operation, you will typically iterate over the results using the "ForEach" iteration statement. Before calling this operation, a value must be assigned to each substitution parameter in the query, if any.

next This operation advances to the next row in a result set. You do not need to call this operation, if using "ForEach" (it automatically does that for you) to access the results.

close This operation should be called after you are finished processing the result set obtained using the "open" operation.

update This operation is used on "Update" type queries - I.e., the SQL statement is an Update, Insert, or a Delete. The given SQL update is executed. Before calling this operation, a value must be assigned to each substitution parameter in the query, if any.
Database Query operations.

Execute

The "Execute" statement is used to call a Routine.

Parameter Seq Description
In (Data path) 1 The first parameter to the Routine - this is optional, if provided the Data path must point to an existing node in the Data tree.

Out (Data path) 2 The second parameter to the Routine - this is optional, if provided and the Data path does not point to an existing node in the Data tree, an empty node is automatically created.

Return Value (Data path) 3 The Data path to accept the return value from the Routine - this is optional, if provided and the Data path does not point to an existing node in the Data tree, an empty node is automatically created.
The Execute statement.

Execute2

The "Execute2" statement is used to call a REST Entry point (ENTRY-POINT) logic as if it was a routine. The Entry point must be declared within the same project. Note that the REST service is not called using HTTP - to call a service use the WsCall statement.

Parameter Seq Description
URL (text) 1 The URL as defined in the ENTRY-POINT declaration of the service.
The Execute2 statement.

ExportXml

The "ExportXml" statement is used to serialize the contents of the Data tree under a node into an XML string. While the @_XML pesudo attribute allows you to do the same, this Statement lets you specify an XML Namespace for serialization.

Parameter Seq Description
Node (Data path) 1 The root of the node to serialize.

Target (Data path) 2 Where to put the serialized output.

Namespace (text) 3 The XML Namespace to use when serializing.
The ExportXml statement.

ForEach

The "ForEach" statement iterates over all instances of an element or all rows in a result set. (Database or MongoDB collection) See Iterating over Nodes/Rows for details.

Parameter Seq Description
Node (Data path) 1 The path identifying the set of nodes to iterate over.

On Loop Var (Drop-down) 2 The variable to use as the loop variable.

Where expression 3 "Where expression" is optional, and it allows you to automatically filter out nodes using a test expression. Only nodes where the expression evaluates to true are processed.

The Where expression has another useful use - it allows you to iterate over the Table records or MongoDB documents without doing an explicit 'open' and 'close' operations on the Table/Collection. You can specify a expression, and that expression is converted to appropriate SQL or Mongo filter for the fetching of the result set.

This also saves you the trouble of writing actual SQL WHERE and Mongo filter expressions. Also, your code reads more naturally without the mixed SQL and Mongo syntax.

Program Block 4 The Logic builder will create a block for you to enter the block of program.
The ForEach statement.

if

The "if" statement is same as the if statement in most programming languages. It is used for conditional execution - it takes a condition and a program block, which is executed once if the condition is true. The "if" statement can have additional "else if" statements attached to it - each with its own condition and a program block. In the sequence the block corresponding to the first condition that evaluates to true is executed. Typically, the last "else if" is without a condition, which means that the last block will be executed if none of the conditions were true.

In Logic Builder, you can add additional "else if" blocks using the special command button provided on the "if" block.

Parameter Seq Description
Test (Expression) block 1 The condition expression.

Program Block 2 The Logic builder will create a block for you to enter the block of program.
The if statement.

Java

The "Java" command is used to write Java code in-line. If you have a small Java code to execute, it is more convenient to write it in-line without having to create a METHOD. This simplifies your code and does not interrupt the flow of logic.

Parameter Seq Description
Java program 1 Any Java program that you can write in a METHOD, you can write here.
The Java statement.

JmsSend

The "JmsSend" command is used to send a message to a JMS Destination (MQ). Your instance comes pre-configured with two JMS Destinations (one queue, and one topic) - you must first declare the destination you want in your schema.

Parameter Seq Description
JMS Destination (Drop-down) 1 Where to send the message.

Message (Data path) 2 The message to send. This Data path must refer to a leaf-level data element. If you want send XML or JSON formatted string, you must serialize the content manually before call this.
The JmsSend statement.

Mongo

The "Mongo" command is used to access the MongobDB collection.

Parameter Seq Description
Operation (Drop-down) 1 The operation to perform. See Mongo operations below.

Collection name (Drop-down) 2 The Collection on which the operation is performed.
The Mongo statement.

Mongo Operations

All MongoDB operations communicate the success status through the Pseudo element /_STATUS under the Collection name. If you want to check if the operation succeeded, a non-zero value indicates a failure.

After a document read operation (fetch, open or next) the document can be accessed using the pseudo node /_document or its inside contents can also be accessed as if the JSON document hierarchy was present under the Collection node.

E.g., referring {Collection}/Name would cause the document to be extracted under the collection node and then 'Name' JS property would be accessed.

Operation Description
fetch It fetches a single document from the collection. The Id of the Mongo document should be assigned to {Collection}/_id pseudo attribute before calling this. After the call the document can be accessed at {Collection}/_document.

open It opens a cursor on the collection and fetches the first document from the set. After this operation, you will typically iterate over the results using the "ForEach" iteration statement. Before calling this operation, a value must be assigned to the pseudo /_WHERE element containing the syntactically correct Mongo filter expression.

The open operation can be skipped, when using ForEach iteration with a Where expression. See ForEach description above.

next This operation advances to the next document in a result set. You do not need to call this operation, if using "ForEach" (it automatically does that for you) to access the results.

close This operation should be called after you are finished processing the result set obtained using the "open" operation. This can be omitted when using ForEach iteration with a Where expression. See ForEach description above.

save This operation saves the document in the collection. If a document has been fetched using "open" or "fetch", the same row is updated (using the Id value), otherwise a new document is inserted.

insert This is like "save", except it always forces an insert of a new document.

delete Deletes a single document from the Collection based on the Id value. The Id of the document should be assigned to the /_id pseudo element before calling this operation.

clear Deletes multiple documents from the Mongo Collection. Before calling this operation, a syntactically correct Mongo filter expression should be assigned to the /_WHERE pseudo element, which is used as the filter for documents to be deleted.
MongoDB operations.

Node

The "Node" statement is used to invoke various operations on a Data tree node.

Parameter Seq Description
Operation (Drop-down) 1 The node operation to perform. See Node operations below.

Node 1 (Data path) 2 The first parameter - see Node Operation.

Node 2 (Data path) 3 The second parameter - see Node Operation.
The Node statement.

Node Operations

Please note that there is no operation for exporting xml - this functionality is available in ExportXml command.

Operation Description
touch This operation simply makes sure that the node exists in the Data tree, if not, an empty node is created. The touch operation is also performed on the second node, if provided.

delete This operation deletes the node and the entire sub-tree under it. The delete operation is also performed on the second node, if provided.

clear This operation deletes everything under the node, leaving the node itself unchanged. The clear operation is also performed on the second node, if provided.

serialize This operation serializes the first node in an internal format and the result is put in the second node. Please note that it uses an internal format for serializing - though readable, not of much use for exporting outside the project.

deserialize Deserializes the string that was obtained using the serialize operation above. The contents of the first node are taken as a string and the deserialized output is created under the second node.

importxml Deserializes the string from the XML format. The contents of the first node are taken as a string and the deserialized output is created under the second node.

importhtml Deserializes the string from the HTML format. The contents of the first node are taken as a string and the deserialized output is created under the second node. HTML is like XML except they are not required to be well-formed. HTML strings are, sometimes, human produced and don't always have matching opening and closing Tags. The HTML parser works around it and still creates a Data tree from the string.

importjson Deserializes the string from the JSON format. The contents of the first node are taken as a string and the deserialized output is created under the second node.

exportjson This operation serializes the first node in the JSON format, and the result is put in the second node.
Node operations.

NodeCopy

The "NodeCopy" statement is used to copy a node and its entire sub-tree to another node. Please note that the structure declarations of the source and target should match. It copies the elements by name, and if a name is not present in the target declaration, the element is skipped. You can use NodeCopy where some of the names are common to source and target declaration - it will copy the matching ones.

Parameter Seq Description
From (Data path) 1 The root of the source node.

To (Data path) 2 The root of the target node. If it does not exist, it is created.
The NodeCopy statement.

NodeInit

The "NodeInit" statement is used to initialize a node in the Data tree from a static XML. Note that you can achieve the same result by assigning a string value to the @_XML pseudo attribute. However, this statement is useful when dealing with large static XMLs. The XML text should be declared in your Schema as XML-STUB.

Parameter Seq Description
Node (Data path) 1 The root of the node to initialize. If it does not exist, a blank node is created.

Xml Stub (Drop down) 2 The XML string from where to initialize the node. Please note that the structure of the XML must match the declaration of the Node structure. Any elements not found in declaration are skipped.
The NodeInit statement.

Return

The "Return" statement is same as the return statement in most programming languages. It causes the currently executing routine to return immediately and resume processing from the line following the "Execute" statement, from where it was called. If not used inside a Routine body, it acts like Abort and the causes the service to end. An optional condition can be specified, if the "Return" action is conditional.

The Routines in , like in most programming languages, have a return value. When used in a Routine, an optional return value can be specified.

Parameter Seq Description
Test (Expression) block 1 This is an optional parameter. If specified, the Return action is taken only if the expression evaluates to true.

Return value (String, Number or Data path) 2 The value to return from the routine. At the time of calling the Routine (Execute), if a Data path was provided to receive the return value, it is updated with this value.
The Return statement.

Sleep

The Sleep command is used to create a delay - the execution is suspended for the given time and thereafter resumes normally.
Parameter Seq Description
Time (ms) 1 The number of milli-seconds for which to sleep. An integer number should be provided. Alternatively, an '@' followed by a data path can be provided to indicate that the value stored in the mentioned node be used for the sleep time value.
The Sleep statement.

WebScrape

The WebScrape command is used to initiate and interact with a Web Scraping Session. ZOAPIIO uses a real browser under the control of Selenium automation toolkit for scraping.

Parameter Seq Description
Sub-Command (Operation) 1
  1. open - Open a new session.
  2. close - Close the session and release Scraper node.
  3. click - Click on an element.
  4. jsclick - Click on an element using JavaScript command. Rarely needed by try it if the 'click' is not producing right effect.
  5. movenclick - Simulate a human click - move the cursor a little to create an impression that a human is doing the clicking.
  6. mouseover - Move the mouse over the node (triggers onmouseover event on the element).
  7. waitfor - Wait for the given node to appear in the page.
  8. awaitcaptcha - Similar to waitfor but issues a console alert for the operator to solve Captcha on the Browser session. This command is only useful when using the "Edge" scraping pool. See details under Scraping.
  9. scrollto - Scroll to and bring the element into view.
  10. refresh - Execute browser refresh.
  11. back - Execute browser back.
  12. screenshot - Takes the screenshot of the browser window and returns in the named path as base64 encoded Data URL.
  13. download - Return the last file that was downloaded in the browser. The content is returned in the named node as base64 encoded data and the name of the attachment (download) is returned as the _NAME attribute of the same node.
  14. iframe - Switch to the Iframe document in the browser - the iframe element must be provided in Node. A blank path implies root document.
  15. window - Switch to the window with the given element (if the browser app has opened multiple windows). Make sure to provide path of an element that is only present in the target window. A blank path implies home window.
  16. reattach - Not used.
Scraper 2 The name of the scraper. The WEB-SCRAPER should be declared in the schema and named here.

Node 3 The path identifying an HTML element in the Web page. If the path is absolute (starts with '/'), the Scraper name must be the first component as in - '/{ScraperName}/...'.

Timeout (sec) 4 Some Scraper operations can be set to timeout, if it is taking too long to complete. The timeout value is in seconds.
The WebScrape statement.

WebSocketGet

The WebSocketGet command is applicable only inside an ENTRY-POINT-WEBSOCKET. Web Socket is a persistent connection with two way communication. This means that once the service is invoked, the client can also send data to the server.

This is a non-blocking call, if data is available it is returned otherwise it does not block. Your service, as it is streaming data to the client, can periodically read the data coming from the clients and take action like changing its behavior or streaming content.

Parameter Seq Description
Data Node 1 The data if available, is returned in this node.

Type Node 2 The data type is returned in this node.
The WebSocketGet statement.

WebSocketSend

The WebSocketGet command is applicable only inside an ENTRY-POINT-WEBSOCKET. Web Socket is generally used to stream data to the client. The WebSocketSend is used to push data to the client. This should be executed in a loop to continuously send data.

Parameter Seq Description
Data Node 1 The node containing the data to be sent.

Data Format 2 When sending data you must specify the format of the data. The options are "text" or "base64". The base64 indicates that the data to be sent is binary and is provided in base64 encoding.
The WebSocketSend statement.

While

The "While" statement in is same as the while statement present in most programming languages. It takes as input, a condition, and a program block - the block is repeatedly executed until the condition becomes false. The condition is checked before entering the block.

Parameter Seq Description
Test (Expression) block 1 The condition expression.

Program Block 2 The Logic builder will create a block for you to enter the block of program.
The While statement.

With

The "With" command works like ForEach, except that only one Node is processed.

WsCall

The "WsCall" statement calls a Web service (Web-API). The service to be called should be declared as WEB-SERVICE in the project schema. At the time of calling, you must provide a Data path representing the input to the service and a Data path to receive the output from the service.

The Web service is called asynchronously - implying that only the request is dispatched without waiting for the response to arrive. The execution continues with the next statement. The reason for asynchronous call is that the Web-service can take a significant amount of time and your program may want to perform some other tasks in the meantime. Another use for this that your program can issue multiple Web-Service calls simultaneously so they all work in parallel.

With the Web service, you specify a program block which is executed when the service completes, and the data is received. Typically, you can leave this block empty. You should use the "WsControl" command to control (wait for or stop) a previously started Web Service.

Parameter Seq Description
Web Service (Drop-down) 1 Data path of the Web service to call. Please note that this is not the name of the web service but the path - implying that it has a slash in front. E.g., if the WEB-SERVICE is named MyWebService, then this field would be /MyWebService.

In (Data path) 2 The Data path of root node for input to the Web service - this is mandatory.

Out (Data path) 3 The Data path of root node for output from the Web service - this is mandatory and if the Data path does not point to an existing node in the Data tree, an empty node is automatically created.

Program Block 4 The program block to execute when the service complete. The Logic builder will create a block for you to enter the block of program.
The WsCall statement.

WsControl

The "WsControl" statement controls a Web Service started previously in the program using the WsCall statement.

Parameter Seq Description
Operation (Drop-down) 1 The control operation to perform. See WsControl operations below.

Web Service 2 The Web Service path that was specified at the time of WsCall. This is optional, and defaults to all services started so far. So, you can initiate multiple Web service calls in parallel and wait for all of them complete with one statement.

Timeout Sec (Free text) 3 In case of the 'wait' operation (see below), the maximum number of seconds to wait. If timeout happens before the services complete, the wait operation will return immediately.
The WsControl statement.

WsControl Operations

Operation Description
wait This operation will wait for the named service or all pending services running at that time.

interrupt This operation will interrupt the named service or all pending services running at that time. I.e., it will cause them to stop without waiting.
WsControl operations.

WsSyncCall

The "WsSyncCall" statement is equivalent to a 'WsCall' with an empty program block, followed by a 'WsControl wait'. It results in synchronous calling of the service.

Xslt

XSLT is an XML based scripting language that allows XML documents to be transformed. It operates by reading an input XML, applying the transformation, and then writing to an output XML. This used to be a popular mechanism to deal with XML processing, although it is losing popularity now. If you have an XSL script or have a transformation that can be achieved easily using XSL, you may want to use it. It is an advanced subject, and unless you have XSL programming knowledge, you are better off without it.

allows you to incorporate XSLT scripts in your programs, through the "Xslt" statement. You need the XSLT script, separately developed, and tested, and then declared as "XSLT" in your project schema.

Parameter Seq Description
Xslt (Drop down) 1 The reference to the XSLT script already declared in your project.

Source (Data path) 2 The root of the node to be used as input to XSLT.

Target (Data path) 3 The root of the node where XSLT output will be created.

Parameters (Data path) 4 The Data tree node containing the parameters to XSLT.
The Xslt statement.