Advansys Formativ 2.0.1 API Overview

[Support 3]

The Advansys Formativ 2.0.1 API is a COM/XML based API allowing third parties to interact with Formativ from processes external to GroupWise. The API lets third parties:

• Check if an applet is available to be executed.
• Execute an applet.
• Write the value of the Utilities.TransferData property.
• Read the value of the Utilities.TransferData property.

The API can be accessed from any COM aware development environment, including Delphi, Visual Basic, C++, Visual Basic Scripting Edition, C#, VB.NET and Microsoft Office products such as Excel and Word.

Contact Advansys support (support@advansyscorp.com) for the Formativ API guide and Authorization keys.

See the example (Visual Basic Scripting) below to the use the formativ API:

• The CallableByAPI Attribute
  Only applets containing the CallableByAPI attribute may be executed using the API. Any attempt made to run an applet which does not contain this attribute will result in an error condition being returned.

  The CallableByAPI attribute is a specially formatted comment which you include in your applet source code. It takes the following form:

  
  
  [attribute: CallableByAPI("")]
  
  

  To limit applet execution to calling applications which include specific authorization keys, you may optionally include one or more API Authorization keys in the CallableByAPI attribute.

  
  
  [attribute: CallableByAPI("Authorization_keys")]
  
  

• Creating an API Session

  
  
  Set formativAPI = CreateObject("Formativ.FormativAPI")
  
  

• Executing an Applet
  The Formativ API is a restricted service that requires an authorization key. Authorization keys may only be obtained from Advansys. The XML passed to the Execute method must include this key as an attribute of the <api-request> element. Use the <execute-applet> element to execute the given applet. Supply the short name of the applet (no path, no extension) as the text value of the <execute-applet> element. The API checks that the applet exists on the target machine prior to executing the applet. See the examples below for more details.

  
  
  iXml = "<?xml version=""1.0""?><api-request key=""Authorization_keys"">" _
  
  & "<execute-applet>APPLET_NAME</execute-applet></api-request>"
  
  iReturnValue = formativAPI.Execute(iXml)
  
  

• Check the return value
  Sample Return Value (i.e returnValue):

  
  
  <request-processed>true</request-processed>
  
  <request-return-value>ok</request-return-value>
  
  

• Checking if an Applet is Available
  Use the ‘applet-available’ element to check if an applet is installed on the target system. Supply the short name of the applet (no path, no extension) as the text value of the ‘applet-available’ element.

  Sample Request:

  
  
  <?xml version="1.0"?>
  
  <api-request key="Demo-111111">
  
  <applet-available>Test</applet-available>
  
  </api-request>
  
  

  Sample Return Value:

  
  
  <?xml version="1.0"?>
  
  <api-response>
  
  <request-processed>true</request-processed>
  
  <request-return-value>ok</request-return-value>
  
  </api-response>
  
  

  If the applet does not exist, the value of the <request-return-value> element will be false.

Flexalocking Applet containing CallableByAPI attribute

You may wish to distribute your solutions to third parties, but not want to make the source code of your applets available. Formativ provides two ways to stop end-users accessing the source code of your applets: Flexalocking and Encoding. Please see the “Developers Guide” about steps to flexalock or encode your applet.

When flexalocking your applet, CallableByAPI attribute need to be placed after the flexalock marker. See example code below for more information.

const IDS_HELP                   = "Help..."

const IDS_ABOUT                  = "About..."



'-->Flexalock



'[attribute: CallableByAPI("")]





Sub Main(Client, GWEvent)



msgbox "Test"



End Sub

Sample code

– C#: Executing a Formativ Applet using Formativ API:

Using directives:
using System.Reflection;
using System.Diagnostics;

// Execution syntax.

string executionSyntax = "<?xml version="1.0"?><api-request key="Authorization_keys"><execute-applet>FormativAppletName</execute-applet></api-request>";



// Get the class type and instantiate Formativ API.

Type objClassType = Type.GetTypeFromProgID("Formativ.FormativAPI");

object objApp_Late = Activator.CreateInstance(objClassType);





object[]  Parameters = new Object[1];

Parameters[0] = executionSyntax;

object retrunValue = objApp_Late.GetType().InvokeMember("Execute", BindingFlags.InvokeMethod, null, objApp_Late, Parameters);



// Return value

string executionInformation = retrunValue.ToString();

Trace.WriteLine(executionInformation);

[This message was edited by Support 3 on July 20, 2009 at 05:48 PM.]

Topic