Creating your first Server Side Object

Overview

Server Side Objects (SSO’s) provides extensibility to the PROIV Low Code framework. Written in Java these class libraries provide limitless integration opportunities with 3rd party software applications that compliments your own solution. Whether you want to integrate with MS office, such as Word and Excel, create PDF documents, or send a SMS text message to a mobile device as a few examples, a SSO can facilitate this integration when a web service is not available or feasible to use.

As the name (Server Side) suggests, these java objects runs on the server (where PROIV is installed), not on the client as ActiveX controls.

Some further examples could be as follows:

  • Create Excel Spreadsheet (Pre-Built)
  • File Transfer Integrations (Pre-Built)
  • Create PDF Documents (Pre-Built)
  • Send Text Messages or Emails (Pre-Built)
  • Credit Card Processing
  • Shipping API Integration
  • EDI Interface Integrations

Writing and using your first SSO for use within your PROIV application.

The “PROIV SSO Gallery” enables you to browse your filing system for a JAR file, which it then scans for available classes. Having selected a class, you can save it to the PROIV server as an SSO definition with an associated nickname.

These SSO definitions can then be used in “Function Definition Headers” to declare SSO instances, each with a unique tag name in PROIV functions. These SSO instances can then be referenced in logic via the tag name to access properties and invoke methods.

Instance of SSO’s can also be passed between PROIV functions as input parameters. If the function is a Global Function, there is an additional tab called “SSO Parms” on the “Function Definition” window. The SSO’s listed on this tab are not created when the function is run, but are passed by the caller function via an interface map. The SSO instances may then be referenced in the called function by tag name specified in the “SSO Parms” list.

When you develop Java class files to be used as SSO’s and called from PROIV logic, you have to follow some development guidelines given in this document later in SSO Development Guidelines section.

 

Below is some sample Java code of the SSO Math Demo class, where we will provide 4 different numbers and then calculate either the SUM or AVERAGE of those 4 numbers. We also have additional methods to retrieve the value of each individual number back in PROIV logic. The path names used below assume that you are using PROIV in a windows environment so you would need to adapt these if you are using a different platform such as Linux
step1step1_1

Compile the Java Source code to java class (runtime) file as follows(assuming you are running PROIV on a windows machine):

C:\>cd com/northgatearinso/proiv/sso/demo
C:\com\northgatearinso\proiv\sso\demo>javac MathDemo.java (it will create the class file MathDemo.class)

Create the JAR file to be distributed and loaded in PROIV:

C:\com\northgatearinso\proiv\sso\demo>cd C:\
C:\>jar -cvf mathdemo.jar com\northgatearinso\proiv\sso\demo\MathDemo.class

 

How To Call SSO (Service Side Object) From PROIV?
So now that we have built our SSO we need to expose this to PROIV so that the SSO Gallery can find it in order that you can import the relevant classes that your require for integration with your PROIV app.

Pre-Requisites:

  • Java Version 1.6 onwards
  • PROIV Version 8 onwards

Here are the steps to import the JAR file and call it from PROIV function:

Step 1:

Copy your jar file mathdemo.jar in to …\VirtualMachine\javalib folder.
Step 2:

Go to Tools >> SSO Gallery

step2

Step 3:

Click on SSO Gallery Icon (see above), it will open a new  window as shown below. Select your jar file and select the Java Class you want to use in PROIV. It will prompt you to assign a Nickname to that class. We will pick our class we created earlier.

step3step3_1

Step 4:

Create new function TestMathSSO and go to Main Cycle, Open the Function Definition and Select the SSO Tab, the following window will open. Select your nickname and assign new tag name to the SSO nickname defined in Step 3 above. This tag name will be used by your PROIV function to reference the java object.

step4

STEP 5:

The following PROIV code shows how to use the tag name we created to access the setNumber[1..4]() public method. The method accepts Integer (Numeric) parameters. We can assign the values to those parameters exactly the same way as we would for GLOBAL_LSCALL in PROIV.

step5step5_1step5_2

SSO Development Guidelines

As with all Software development, to ensure that you build compliant and supported SSO’s you must follow some guidelines that are summarized below, these are also well documented in the PROIV documentation set and provides further information.

Constraints:

  • SSO nicknames and tag name are case sensitive
  • SSO nicknames are limited to 32 characters in length
  • SSO tag names are limited to 32 characters in length
  • ‘char’ and ‘string’ data types are subject to character-set conversion, which is dependent on the JAVA_CHARSET setting in the pro4v[n].ini file.

PROIV Behavior

  • ‘static’ data is shared between all SSO’s of the same type in a single Client session.
  • Parameters provided in an interface map or an SSO method call is always direction ‘input’
  • SSO parameters for PROIV function calls, can only be direction ‘input’ in interface maps.
  • Type check is preserved for SSO methods calls.

Properties:

  • SSO method and property names are case sensitive
  • SSO method and property names are truncated to 32 characters in length
  • Properties must be ‘public’ and of the Simple-Alpha-Numeric data type includes all of basic data types (boolean, byte, char, short, int, long, float and double), as well as the java.lang.String.
  • Attempting to set a property as ‘final’ results in a java.lang.IIlegalAccessExcpetion exception.

Method:

  • SSO methods return one of the following types:
    • Basic Types: Boolean, byte, char, double, float, int, long and short.
    • Objects, e.g. java.lang.String or java.lang.Integer
    • void
  • Methods must be ‘public’, not ‘abstract’ or ‘overloaded’, and the parameters must be of the Simple-Alpha-Numeric data type. The return type can be any non-array data type, but objects are converted to strings via the toString() method.
  • Method overloading (class to have two or more methods having same name, but differing parameter types) is not supported.
  • No support is provided for array handling with PROIV SSO methods. For example, arrays cannot be supplied as parameters to an SSO method. Also, SSO method calls cannot return arrays.
  • Only numeric and alphanumeric parameters to SSO methods are supported.

 
PROIV V8.0 delivers a number of pre-built SSO’s that you can use within your applications to facilitate integration with third party apps these include.

  1. @ExcelWriter – Creates Microsoft Excel Spredsheets from PROIV function.
  2. @PDFWriter – Creates PDF documents from PROIV function, without the knowledge of XML and XSL.
  3. @FTPClient – Simple FTP (File Transfer) from PROIV function.
  4. EmailSSO – Send an email from PROIV function, including attachments.

If you want further information on these provided SSO’s you should refer to the PROIV documentation, in addition you can access the complete java documentation of the above and other distributed SSO’s by opening the ‘index.html’ page from the following location (on you PROIV server, based on your install directory) to your browser window:

<PROIV Install Folder>\ManagementServices\webapps\VirtualMachine\admin\docs\index.html

javadoc