Practical smartUI: Reading complex categories on the Content Server Side

Normally, when building REST Services for smartUI, you’ll have to read complex attributes from categories to send them for display to a widget.

Lets use this example

A complex Category with 4 Sets and Table Key Lookups
A complex category with multible sets and table lookups (click to enlarge)

In your REST handler, you r task would be to get the values of the category attached to a node, read them and send them to the client using REST.

In this writing, we’ll focus on the “Read them” part. Our trick is

object  LLNODE = $LLIAPI.LLNodeSubsystem.GetItem(node.pSubtype)
result = LLNODE.NodeCategoriesGet(node)

Thos gives us all Categories connected to a node.

When we receive the REST call in ther server handler, we should do

  1. find the node id of the the object to examine.
  2. find the categories attached to this node (Red Arrow in the Screenshot)
  3. iterate over all categories and get the attributes we want. This is based on
    1. the attribute definitions (Green Arrow on the Screenshot)
    2. the attribute values (Yellow Arrow on the Screenshot)
  4. if you encounter a set (-18 as attribute type), you also will have to iterate over the set (Red Rectangle)
Get the Values of a complex category
The REST Handler to get the Values of a complex category

Lets take a look on the Values of a single Category. They are inside an assoc with one entry per attribute id.

i

The Value list in CSIDE
The value list in CSIDE

Now you are almost done. Put a switch construct to get all values of the attributes on which you are intersted and get them out of the fdata assoc. The Value is found in the fdata assoc of the n-th Category unter the content of the first Value entry. Then we have to pick the attribute id where we find the content of the attribute in the first Value entry.

The Str,ValueTostring typecasts the output to be a string. So when we finished the job, we’ll see in the entry event.eventcycle the value of the attribute with the name “EventCycle”.

Get the attributes of interest
The switch construct to get the attributes of interest

The only thing to do is put the values in assocs and send them to the smartUI widget under the main clause “events” in the JSON array

Sent the values back
Send the values back. Support 200 (ok) and 500 (error) as status code.

So you see, Categories are no Monsters. They are quite user friendly. Using the same mechanism, you can even update complex Categories with one REST call.

Happy smartUI programming.

New: We are offering custom widget development. Interested? Send an e-mail to merz at ebit-company.de stating the purpose of the widget and requesting a qoute

Technical Training “How to program a Widget in the new Content Server GUI” with the CSUI SDK

Hi folks

Beeing Content Server Trainer, I was asked to provide a training “How to program a Widget for the new Content Server GUI” to several customers. This is about the content of such a training and the reason why such a training is technically really advanced.

CSUI SDK introduces a shift in paradigma, the server is no longer providing the GUI, all is done by a Javascript Application at the client side.

Basic Training (newest version 1.005 from Feb/2018)

The basic training is very compact and lasts 5 days.

First, lets take a look on the components:

As a prerequisite, a firm knowledge of CSIDE, How to build a module, the Node Structure and whats to do with Content server Nodes is necessary.

At the end of the training, you’ll have a working knowledge of:

  1. Content Server Perspectives. What are they and how you can use them to provide a user specific interface.
  2. Content Server REST. This is the only possibility for the client to communicate with the server, so its mandantory to know the REST interface from the application point of vue. And, as REST can be very slow due to unneccesary data, its also mandantory to know, how to add REST services to the Content Server to get the data you want in the fastest way.
  3. Javascript. There are Javascript Patterns, which are used heavily in the SDK. If “Javascript Object Inheritance”, “Currying/Schoenfinkelizing”, “Decorators” etc are weird words for you, this chapter is the right chapter for you.
  4. Next is the infrastructural world of the sdk.

    CSUI Components
    The CSUI Components

    There are several components, which must be understood prior to build a Widget.

    1. node.js is the base Javascript system for our development
    2. grunt.js is a Javascript task runner, which we use to build, test and debug our widget
    3. yeoman is a scaffolding system, which will be used by a Opentext extension to initialize the development folder. It also creates the skeleton of a Content Server module, which is used as a “Carrier” for our Widget(s)
    4. backbone.js is the base framework to be used
    5. marionette.js is an extension to backbone.js, making Views easier.
    6. handlebars.js is the html templating framework used in the sdk
    7. require.js is the javascript module loader to be used
    8. bootstrap.js/binf.js is originally the public domain CSS/JS framework from Twitter for the appearance of the Widget. Binf is the Opentext variant, allowing to override CSS without negative effects
  5. Next is the SDK itself. Due to time restrictions, in the base training are only the base functions, the advanced training covers the other aspects. It contains
    1. Installing the SDK
    2. Building the Demo Widget
    3. CSS Style Overrides binf
    4. General Overview of the SDK
    5. Content of the SDK
    6. Routing (Preview of the Advanced Training)
    7. New Commands
    8. Custom Columns
    9. Metadata
    10. Define a new NodeType
    11. Create a Widget
    12. Base Widgets
    13. Controls
    14. Models
  6. Mockup and Test Data. How to setup mockup REST data. How to build test facilities in the SDK
  7. Anatomy of the Hello Widget. A walktrough through this widget
  8. Anatomy of the MyAssignment Widget
  9. Add another Widget to the Content Server. Change the Hello Widget and add additional fields
  10. Build a Custom Widget to be used as Client with a custom REST service. Here, a custom widget is build, which uses an extended version of the custom REST service from Part 2.
  11. If time allows: Some Tips and Tricks from a “Work-in-Progress” Widget

 

Advanced Training (Version 1.005 Feb/2018)

OK, thats the basic training. There are a lot of additional things inside the SDK, but to understand these, there must be a couple of weeks with practical experience in between. The advanced part has beed remodelled to include a couple of interesting things.  The advanced part contains:

  1. Chapter 1 Extended SDK Parts
    1. Additional Widgets
      1. NodesListReportView
      2. TilereportView
      3. FilteredCountChartView
      4. Carousel Widget View
      5. Userwidget eSocial
      6. ActivityFeedWidgetView
      7. ActivityFeedContent
      8. ChatWidget
    2. Datepicker
    3. switch
    4. Workflow (new in Content Server 16.2)
      1. Workflow Components
      2. Workflow in smartUI
      3. Starting Workflows
      4. URL Routes
      5. Workitem Actions
      6. Workitem Extension
      7. Writing Workflow Extensions
    5. New REST API Support (16.2) for Workflows
    6. Widgets not part of the SDK
      1. Mobile Scanning
      2. xECM: Header Widget with Business Object Infos
      3. xECM: Snapshot of current document Attachments
      4. xECM: Dossier View Widget
      5. Engineering Doc Management: Search
      6. xECM: Office365 Groups
  2. Chapter 2 Extended SDK Features
    1. Build Language Packs for Internationalization
    2. Commands
      1. Implementation and Inheritance from “CommandModel”
      2. Best Practices
      3. Using Commands
    3. Custom URL Router. Routing, adding custom Routers. Using Routers as Navigation.
    4. Behaviours. What are Behaviours?
      1. DefaultActionBehaviour
      2. BlockingBehaviour
      3. ExpandingBehaviour
      4. InfiniteScrollingBehaviour
      5. PerfectScrollingBehaviour
      6. PageLeavingBehaviour
    5. Mixins. What are Mixins? All available Mixins.
    6. Browsable Support for Collections. Using the “Browsable” support for Model-Collections.
  3. Chapter 3 Additional Things to consider
    1. Tips and Tricks (Work in Progress- List can change)
      1. Add a OTDS Ticket already in the browser to the connection object
      2. Re-using a OTDS Ticket as LLCookie
      3. Checking the paths in the test/index.html
      4. Using Helpers for supporting a select box with Handlebars
      5. Adding non CSUI supported JQuery functions in a view
    2. Handlebars advanced. A deeper look into Handlebars
    3. LESS advanced. A deepter look into LESS, the CSS language used in Bootstrap
    4. Accessibility in Bootstrap. What can be done to add support for screenreades etc to Bootstrap/Binf? Whats to avoid? Which tools are available
    5. Best Practices in Development

 

As you can see, there is a lot of stuff. The basic training last 5 days, the advanced training 2. But on the other side, you’ll get happy users with your new Widgets.

And that’s all what counts.

References

Javascript
  • “JavaScript Application Design “as a general introduction (covering Grunt) https://www.manning.com/books/javascript-application-design
  • Stoyanow’s JavaScript patterns http://shop.oreilly.com/product/9780596806767.do
  • Flanagan’s “JavaScript: The Definitive Guide” http://shop.oreilly.com/product/9780596805531.do
  • Crockfords “Javascript The good Parts” http://shop.oreilly.com/product/9780596517748.do
  • Flanagans “JavaScript Pocket Reference” http://shop.oreilly.com/product/0636920011460.do
Bootstrap
  • Spurlock: Bootstrap Responsive Web Development http://shop.oreilly.com/product/0636920027867.do
  • Syed Fazle Rahman: Jump Start Bootstrap: Get Up to Speed With Bootstrap in a Weekend https://www.amazon.com/gp/product/0992279437
  • Alan Forbes: The Joy of Bootstrap: A smarter way to learn the world’s most popular web framework https://www.amazon.com/gp/product/1522792813/
Require.JS
  • Greg Franko: Instant Dependency Management with RequireJS How-to https://www.amazon.com/Instant-Dependency-Management-RequireJS-How/dp/1782169067
  • David Sulc: Structuring Backbone Code with RequireJS and Marionette Modules
    https://leanpub.com/structuring-backbone-with-requirejs-and-marionette
Backbone
  • Developing Backbone.js Applications Adnan Osmani http://shop.oreilly.com/product/0636920025344.do
  • js Patterns and Best Practices Swarnendu De https://www.amazon.com/Backbone-js-Patterns-Best-Practices-Swarnendu/dp/1783283572
  • js Cookbook Vadim Mirgorod http://shop.oreilly.com/product/9781782162728.do
  • js Blueprints Andrew Burgess http://shop.oreilly.com/product/9781783286997.do

 

Backbone-Marionette
  • Getting Started with Backbone Marionette Raymundo Armendariz, Arturo Soto
    https://www.packtpub.com/web-development/getting-started-backbone-marionette
  • Marionette.js: A Gentle Introduction David Sulc https://leanpub.com/marionette-gentle-introduction
  • Marionette.js: A Serious Progression David Sulc https://leanpub.com/marionette-serious-progression
Mockjax and Jasmine
  • js Cookbook Vadim Mirgorod https://www.packtpub.com/mapt/book/web_development/9781782162728 Chapter 8
  • KnockoutJS Essentials Jorge Ferrando
    https://www.packtpub.com/application-development/knockoutjs-essentials
  • JavaScript Testing with Jasmine Eva Hahn https://www.safaribooksonline.com/library/view/javascript-testing-with/9781449356729/

 

Content Server Trainings
  • 4-0140 Content Server IDE (CSIDE) Fundamentals
  • 971-301 Livelink ECM Enterprise Server Workflow Customization Fundamentals
  • 03-0117/8 Webreports Design

 

 

Using the CSIDE Code Generation Wizard (1) – Create WebNode Action automatically

In the newer versions of CSIDE, you’ll find a code generation wizard, which writes code snipets for standard tasks automatically.

You can call this Code Generation wizard by clicking on the right mouse button.

Call of the Code Generation Wizard

Next, the Code Generation Wizard gives you a list of all templates, which can be used for the code generation. The amount of templates can vary from CSIDE version to CSIDE version.

List of all Templates to be used for the code generation

When you click on a template, you’ll get further info’s on the template. The amount of info’s can vary from template to template.

Infos on the template

Here in this post, we are using the “Create WebNodeAction” Command. Refer to future posts on examples of the other templates.

A WebNodeAction is a command, which is executed against a node by issuing a WebNodeCommand (in Contenxt/Node or other menus). For example, the “Open” command in a node menu is a WebNodeCommand, which issues the action for opening the node content.

After selecting “Create WebNodeAction”, we must provide two additional definitions.

Additional Infos to provide

First, we must select the package to put this command in. We simply select DELIVERER (the name of our module), but in practical situations, you should select a proper package.

And the name of the command has to be provided. After clicking “Finish”, a file with the name “MyTestCommand.os” will appear in the first level of our OSPACE.

The Command is generated as .os file

When you open the newly created file, you’ll see a complete command definition.

Command Definition Part 1

The fEnabled is set to true. The fWebScript has the default name of “mytestcommand.html” and there is an empty list of fPrototype.

Change the name of the fWebScript to the name you want. Add the Webingo parts of the commands output in this fWebScript.

If you use special parameters in the request, setup the proper fPrototype list.

The _Nodetypes() returns an undefined List, which should be changed immediately to reflect the node subtypes for which the command should be valid.

Command Definition Part 2

There is even a _SubclassExecute stub generated automatically. Add the action code to be executed in this _SubclassExecute stub.

Optional: Connect this WebNodeAction with a WebNodeCommand in a context or node menu or somewhere in the GUI to make it accessible for the end-user.

 

Calling OScript from Java Code (2)

In December 2016, we discussed how to call Java code from OScript . Now, we’ll discuss the other way round, how to call OScript from Java. This can be quite useful, if you want to use your business logic implemented in java against the content server.

The Java code must be put in the ojlib directory (see the previous post on this topic).

As always, if you want to deploy your java code within a module, do this

  • Build your code into jar files.
  • Add the jar files in OTHOME/ojlib/ or OTHOME/module/yourmodule_yourversions/ojlib/ directory (and their subdirectories) to be recognized by Content Serverk JVM’s application classloader.

The base thing is, you call OScript built-in functions through the OScriptObject.runScript method from a java coding.

For example, the java code

OScriptObject.runScript("echo","System.ThreadID()");

will display the unique integer for the current thread ID at the console (or in the logs, if you do not use CSIDE)

You can call all OScript functions and scripts. This example will list all nodes in the enterprise workspace

     // List nodes in the Enterprise workspace.
            result = (Map<String,Object>) OScriptObject.runScript( "$LLIAPI.NodeUtil.ListNodes",
				prgCtx,
				"(ParentID=:A1)",
				args );

prgCtx is the standard rogram Context, args is the ArrayList containing the arguments and A1 points to the first entry in the args array to be used as ParentID.

The next example can be used to get the current user from java coding, extract its userID and then derives the user name from ths user id. A standard logger is used to log the output, replace this with the logger of your preference.

    public static String getUserName( OScriptObject prgCtx )
    throws Exception
    {
        String retval = " user not found";
        
        try
        {        
            // get the user session object
            OScriptObject uSession = (OScriptObject) prgCtx.invokeScript( "USession" );
            // get the userID from the User Session
            Integer userID = (Integer) uSession.getFeature( "fUserId" );
            // display it
            logger.log( Level.INFO, "UserID is " + userID );
            
            retval = "The current login User: " + userID;
            
            // Get the Users name from the User ID
            Map<String,Object> status = (Map<String,Object>)
			OScriptObject.runScript( "$LLIAPI.UsersPkg.NameGetByID", uSession, 1000 );
			
            logger.log( Level.INFO, String.valueOf( status ) );
            logger.log( Level.INFO, (String) status.get( "Name" ) );
        }
        catch( Exception e )
        {
            logger.log( Level.SEVERE, "Caught Exception", e );
            throw e;
        }
        
        return retval;
    }

 

In the next posting on this topic, we’ll discuss the Mappings from JAVA to OScript and vice versa.

 

Execute a Livereport from OScript and get the results

From time to time, you may want to execute a livereport from an OScript function and get the results for further processing. This can be done quite easy.

First, you should have the node id of the report to execute.

In this scriptlet, the node id of this livereport to execute is nodeid

Second, you should setup a list with all input parameters. For each input parameter, create an assoc with inputType, label, prompt, textvalue and value of the parameter.

Add this assoc to the list of input parameters.

Store this list in the pExtendedData field of report node.

Object llnode = $LLiApi.LLNodeSubsystem.GetItem( $TypeReport )
Assoc data = llnode.ExecuteReport( prgCtx.fDBConnect, extdata )

Get the llnode of the report by calling the LLNodeSubSystem.GetItem. Execute the report by using llnode.ExecuteReport

The result of the livereport is in data.contents.

The whole call can look like this:

 node = DAPI.GetNodeById(prgCtx.DapiSess(),nodeid)
 if node.pSubType == $TypeReport // Is node a livereport?
     Assoc extdata = node.pExtendedData
     Assoc inp
    //Create input parameters assoc
     Assoc inp
     inp.inputType = "String"
     inp.label = "inputlabel1"
     inp.prompt = "DataID"
     inp.textValue = Str.String ( DataID )
     inp.value = Str.String ( DataID )
 
     //Attach inputs parameters list to extendeddata
     List inputs = {inp}
     extdata.inputs = inputs
     llnode = $LLiApi.LLNodeSubSystem.GetItem($TypeReport)
     Assoc data = llnode.ExecuteReport(prgCtx.fDBConnect, extdata)
     result.OK=true
     result.data = data.contents
     return result
end

 

Calling Java Code from OScript (1)

Sometimes it would be nice to use existing Java coding from a module instead of recoding this in OScript.

There is a facility in the content server which does exactly this bridging from OScript to Java, the so called JavaObject class. You’ll find the exact documentation in the “OScript API/Build-In Package Index”

In this first post of the series we’ll discuss the  basic calls from OScript.

First, you need some Java Code, compiled and in the form of a jar. Put this jar either in OTHOME/ojlib or (much better) in a ojlib directory in your module structure. After installing the module, the jar(s) are copied automatically to the OTHOME/ojlib. Then, the jvm classloader will find your jar(s).

From OScript it is possible to access static classes and instances.

Static
Dynamic InvokeStaticMethod(String classname, String methodName, List parameters)

Dynamic GetStaticField( String classname, String fieldName)

Dynamic SetStaticField( String className, String  fieldName, Dynamic value)

The return values are either Error or Dynamic if the call is successful.

Dynamic
JavaObject New (String className, List parameters)
Instance
Dynamic GetField(String fieldname)

Dynamic SetField(String fieldname, Dynamic value)

Dynamic InvokeMethod(String methodName, List parameter)

The return values are either Error or Dynamic if the call is successful.

An example
function void javaTest()

   JavaObject myObject

   myObject = JavaObject.new("my.own.package.class")
 
   Dynamic res = myObject.InvokeMethod("myMethod",{"aa","bb})

   if (isError(res))

     echo ("Init failed")

     return

   end

   Dynamic res1 = myObject.GetField("myResult")

   if (IsError(res)) 

     echo("Calculation failed")

     return

   end

   echo("The result is "+res1)

end

In the next post we’ll discuss how to get the JNI exceptions and the error stack from the jvm.

 

Making Configuration Values Cluster Safe

Normally, there is a file called “opentext.ini” in the config directory of your Content Server instance. This file contains a lot of configuration values.

A content server reads this file at boot time.

But, if you use a cluster of Content Servers, its a problem changing all “opentext.ini” files for a configuration value. And rebooting them will use a lot of down-time.

In a cluster, there is another option to store configuation values, the “KIni Table” in the database. This values are read immediately from the content server(s) and do not require a reboot.

From OScript, use the database storage like this

Retrieve a value (from the “MySoftware” Section)- Default Value 50, if this is not existing)

result = CAPI.IniGet(dbConnect.fLogin, ‘MySoftware’,‘StartJob’, 50)

Set a value ( sets StartJob value of MySoftware to 50)

result = CAPI.IniPut(dbConnect.fLogin, ‘NySoftware’,‘StartJob’, 50)

List all configuration values registered under MySoftware

result = CAPI.IniList(dbConnect.fLogin, ‘MySoftware’)

Delete a configuration value (deletes StartJob value from MySoftware)

result = CAPI.IniDelete(dbConnect.fLogin, ‘MySoftware’, ‘StartJob’)

 

The dbConnect.fLogin is the CAPICONNECT(the login object) to the database.

CSIDE Command Add Documentation Comments

There is an interesting command in the newer CSIDE versions.

Add Documentation Comments

This can be found in the menu “Source”

Here is the Documentation Commands Entry

This works like the similar commands in java IDEs or in Visual Studio.

Imagine, you have a source code like this

Source Code without documentation comments

and if you use this new command, you’ll see, your source code is amended with the documentation comments like this

Source Code with documentation comments

This basic documentation comments are only a framework and they should be extended to declare the purpose of the function, the variables and the return values.

Remove Unused Variables in CSIDE

A very interesting function is “Remove Unused Variables” in CSIDE:

Where fo find the command
Where fo find the command

This command will remove all unused variables from the functions in the edit window.

The command at work

At left, you see the declaration “integer s=1”, which is not used in the function. At right, you see, this declaration is deleted after the execution of the “Remove Unused Variables” command

New CSIDE Function Format Source

The new CSIDE function allows a direct format of the OSCRIPT source code inside the IDE.

Imagine this short function in OSCRIPT. This is very unreadable.

By pressing CRTL+SHIFT+F inside the OSCRIPT window, the source code is reformatted automatically and the result looks much more readable: