Ragic Logo
The Ragic Blog
  • Follow Ragic!
  • Ragic RSS FeedRSS
    Subscribe by Email

  • Latest Posts
  • Popular Posts
  • Tags
  • Search
  • Back to Support Home Ragic Builder Workflow Tutorial

    Ragic Builder Workflow Tutorial

    Chapter 1. What is Workflow

    With Workflow you can create your own function to manage your database.This tutorial teaches most things you need to start coding your own Workflow. Workflow is easy to learn. You will enjoy it.

    1.1. Why Workflow

    Even without workflow, there is a handy Formula tag in Ragic to help you deal with simple calculation between fields in the same form.

    However, you might be curious: what if I have to do more complicated things such as inventory management or I need calculation across several forms? In this case Workflow is what you need.

    Actually we can conisder Workflow as JavaScript on server side. With JavaScript and a bunch of default parameters you can call funtions in API easily. In this case, Ragic Builder become more flexible and more capable of handling your specific needs.

    1.2. Categories of Workflow

    There are 5 types of Workflow: Global Workflow, Pre-workflow, and Post-workflow. They are executed in the following order:[Save edit] being clicked → Global Workflow → Pre-workflow → DB written → Post-workflow.

    Categories of Workflow

    1. Global Workflow : Scripts in this workflow will be executed right after Save edit being clicked. One of the important character of global Workflow is that it can access all the fields in the same AP. Therefore it can work with multiple forms.

    2. Pre-Workflow : Scripts in this workflow will be executed right after Global Workflow being executed. The main difference is pre-workflow can only access fields form a single form.

    3. Post-workflow : Basically the same as Pre-Workflow, but being executed after successfully saving all data filled in the fields.

    1.3. API of Workflow

    Workflow can call functions from Ragic API by default variables.Those functions are in the package com.ragic.s3.service.workflow .

    1.4. Default variables of Workflow

    Default variables of Workflow:

    1. db: A dafault object that implements ExecuteScriptWorker. You can find a bunch of important funtions here. For example, addNode and delNode can add/delete a record ,getQuery can get you a SDBQuery object, and getAutoGenerate/resetAutoGenerate/incrementAutoGenerate will function as AutoGenerate field in Ragic forms as you may guess. Also, because ExecuteScriptWorker inherits from BDBSmartWorker, there are several handy getters and setters as well. We will discuss them in the following chapters.

    2. mailer:A default variable implementing ScriptMailer. You can send e-mails by the function sendMail.

    3. param: A default variable implementing ScriptPostParameter/ScriptPreParameter,depending on which workflow you are working on. Noted that param is not implemented in Global Workflow. You can access new/old field value by functions getNewValue/getOldValue. and as for node IDs. Also, an important and useful function when we have to deal with subtable, getSubtableEntry, is implemented in this class as well.

    4. response : A default variable implementing ScriptResponse. With this object you can show messages by pop-up window.

    5. user:A default variable implementing ScriptUser. You can acquire information about current user by functions in this class, such as getUserName,getGroups,isValid, etc.

    6. log : A default variable functions as debugger.

    Chapter 2. Workflow Where To

    This chapter is about where to put your Workflow code.

    2.1. Design Workflow Modules

    Follow the path: [Design] -> [Design Workflow Modules] to find the page as following images show.

    In the page you can choose either Global Workflow or a form in your database, and then choose to edit pre/post-approval or pre/post-Workflow.

    After putting in your program, don't forget to click [save]. Actually we suggest you to click [save] as often as you want just in case.

    Figure 2.1. Example : JavaScript in post-workflow.

    Example : JavaScript in post-workflow.

    Go back to the form. Click [New Entry] then [Save edit]. You will see the result of the program.

    Figure 2.2. Example : Result of [Post-workflow] program

    Example : Result of [Post-workflow] program

    2.2. Form Settings

    While in design mode, you can find the same blank field as we mentioned in last section simply by clicking [Form Settings] -> [Workflow]

    After editing, click [Save edit] to save changes, just like saving data changes.

    Noted that you cannot see line number and keywords when you are editing workflow here. Also you may find that there is no access to global workflow because this path is obviously single-form-oriented.

    Chapter 3. Handy tips of Workflow

    This chapter is about severl useful functions and concepts we would like to tell you before you jump into programming workflow. First thing (you might already know) is that, Workflow is JavaScript on the server side, and it can call functions from Ragic API by default variables. We are going to introduce you some top-rated handy approaches to bring you a quick start point.

    3.1. How to debug

    It is not suprising to know how to debug before how to program.

    Workflow has no powerful debugger like those IDEs, but we have a simple and intuitive tool, log. We had talked about this stuff in section 1.4. Also we took it as example in last chapter. If you can't recall, here is the code again.

    Figure 3.1.  Example : Debug codes

    Example : Debug codes

    3.2. What are node id and field id

    Each field in an AP has an unique ID to be recognized. We call it Field ID. You can find it under Field Name in design mode. Sometimes you will see Domain ID in API Document. It means the same as Field ID does.

    For each field, there will be a value according to each record. Each value has an Id. We call it Node ID. Actually, What we use to identify each record is the Node ID of the key field in a single form.

    Figure 3.2.  Example : This is the first record in this form. Therefore "0" appends to the url of this page. In this case we know that key field node id of this record is 0

    Example : This is the first record in this form. Therefore "0" appends to the url of this page. In this case we know that key field node id of this record is 0

    3.3. How to access Node Id and Value of each field

    Node ID and Value are usually neccesary for most calculations and logic descisions.

    You can call functions getNew/OldNodeId and getNew/OldValue of default variable param if you are editing a pre/post-Workflow. When it comes to Global Workflow, refer to functions getFieldNodeId and getFieldValue of db instead.

    Figure 3.3.  Example : Get Root Node Id by param.getNewNodeId()

    Example : Get Root Node Id by param.getNewNodeId()

    3.4. How to manipulate subtable

    It is very common to put subtable in a Ragic form. Actually each subtable refers to another distinct form. In this case we cannot access data in subtable just by above approaches. What should be done beforehand is to acquire another variable functioning as param but being assciated with the subtable. Here is the sample code.

    Figure 3.4.  Example : How to access data in subtable

    Example : How to access data in subtable

    getSubtableEntry returns a java.util.List<ScriptParameter>, we call it List here. With toArray() we can retrieve each ScriptParameter object inList. Then we can regard it as param and go for the rest of fields in subtable.

    3.5. How to write data through workflow

    As we mentioned in section 1.4, default variable db is an implementation of ExecuteScriptWorker that inherits BDBSmartWorker, therefore we have a bunch of useful setters and getters by hand, such as set/getFieldSelectionValueset/getFieldSelectionValues and set/getFieldValue

    These functions are extremely useful, especially when you are dealing with data writing. Following is an example about how to write data by param.getNewNodeId and db.setFieldValue.

    Figure 3.5.  Example : Writing data on Ragic by db.setFieldValue

    Example : Writing data on Ragic by db.setFieldValue

    Except for changing existing data, it is pretty common to add a new record to Ragic form by Workflow, just like how we make it on usual Ragic interface.

    What we need here are db.addNode and db.setFieldValue. db.addNode is obviously a tool to adding a reocrd, while for db.setFieldValue we already know how to work with it.

    Figure 3.6.  Example : Adding a new record by db.addNode and setting new value to each field by db.setFieldValue

    Example : Adding a new record by db.addNode and setting new value to each field by db.setFieldValue

    3.6. Auto Generate

    In Field Settings there is a field input type, auto Generate, which is usually implemented for generating default sequence ID to identify each record. For instance, the field Toy ID in the above example.

    In Workflow we use some functions in db to manipulate auto generate. Here comes the example.

    Figure 3.7.  Example : Manipulating Auto Generate by db.

    Example : Manipulating Auto Generate by db.

    Noted that if the type of the field is AutoGenerate, the value of this field will be doubly incremented if calling incrementAutoGenerate. Therefore incrementAutoGenerate usually be implemented when dealing with subtables.

    comments powered by Disqus