Adaptiva SDK Usage Guide

In this article:

Overview - Core Concepts - The concepts behind the API Foundry and SDK.
Providing Inputs to Workflows - Passing data into API workflows
Receiving Return Values from Workflows - Retrieving data from API workflow output
Client vs. Server API Calls - Differences between client and server API calls
Synchronous vs. Asynchronous API Calls - Differences between Synchronous and Asynchronous API calls
Target Machines - The machine on which we wish to run the API workflow.
Security for API Calls - The security options for securing API execution
Run-Time Considerations - Working with the runtime libraries
Using the Adaptiva SDK with C and C++ - Exploring the C/C++ code samples
Using the Adaptiva SDK with C# and other .NET Programming Languages - Exploring the .NET code samples
The HelloServer and HelloClient Sample APIs - Specific example- HelloServer/HelloClient
The HelloClient Sample - Specific example - HelloClient
The Async Sample - Specific example - Async
The CommandLine Sample - Specific example - CommandLine

 

Overview - Core Concepts

Adaptiva products are built on top of a powerful platform, internally referred to as the Edge platform. Among other things, the Edge platform provides visual programming capabilities through a drag and drop Workflow designer, which allows Adaptiva product administrators to create Workflows.

A Workflow contains executable logic, similar to a script or a piece of code. Like most pieces of code, Workflows can accept Input parameters, process those inputs when they execute, and generate a set of return values when they finish executing.

The Tool Foundry built into all Adaptiva products allows Adaptiva product administrators to compile any Workflow into an executable tool, which is an actual .exe file.

The Executables generated by the Tool Foundry accept input parameters from the command line, and display their return values on the console as text

The API Foundry built into all Adaptiva products allows Adaptiva product administrators to publish any Workflow as an API, which may be invoked programmatically using the Adaptiva SDK

The APIs published by the API Foundry accept input parameters and provide return values to the calling applications using the methods provided by the Adaptiva SDK

A set of Workflows and APIs are built into Adaptiva products, which allows applications to make use of these APIs without doing the work of creating the necessary Workflows, or publishing them as APIs using the API Foundry

 

Providing Inputs to Workflows

When a Workflow is designed, one or more input parameters may be specified. Each input parameter consists of a name-value pair. The names and values have the data type 'TEXT'.

The person designing the Workflow provides the name of the input parameter, and the person executing the Workflow provides its value

When the workflow is executed as an API, the input parameters retain their behavior, and become the input parameters of the API itself

The Adaptiva SDK provides methods to pass input parameters as name-value pairs to any API that the developer wishes to invoke programmatically.

 

Receiving Return Values from Workflows

When a Workflow is designed, one or more return values may be specified

Each return value consists of a name-value pair. A set of predefined return value names have been provided in the Workflow Engine, and are listed below. Return values may have any data type, and the data types of all the built-in return values are listed below.

List of return values, and their corresponding data types:

• ResultBoolean: Boolean
• ResultText: String
• ResultWholeNumber: 64-bit Signed Integer
• ResultFractionalNumber: Fraction/Decimal
• ResultDateTime: Date-Time
• ResultArrayOfBoolean: Array of Boolean
• ResultArrayOfText: Array of Strings
• ResultArrayOfWholeNumbers: Array of 64-bit Signed Integers
• ResultArrayOfFractionalNumbers: Array of Fractions/Decimals
• ResultArrayOfDateTime: Array of Date-Time

When the workflow is executed as an API, the return values retain their behavior, and become the return values of the API itself

The Adaptiva SDK provides methods to retrieve return values as name-value pairs from any API that the developer wishes to invoke programmatically.

 

 

Client vs. Server API calls

For security reasons, the Workflow engine provides a clean separation between server and client workflows. This separation is carried over to the Tool Foundry and API Foundry, for the same reason.

Every Workflow and API is fundamentally executable either on the Adaptiva server machine, or on Adaptiva client machines, but never on both types of machines.

The Adaptiva SDK supports this separation by providing a Boolean input parameter on its methods, which allow the calling process to explicitly specify whether an API is intended to be executed on the client or server.

The second overload on the AdaptivaApiFoundry.Api constructor allows us to specify a boolean as the first property to indicate whether this is a server API (workflow).

Server = false: API will execute on the calling client.
Server = true: API will execute on the Adaptiva Server.

 

 

Synchronous vs. Asynchronous API calls

The Adaptiva SDK supports two types of invocation behaviors:

Synchronous execution:

The caller invokes an API. The calling thread is blocked (made to wait) until the API finishes executing. The API finishes executing and the calling thread can immediately use the return values that resulted from the API call.

Asynchronous execution:

The caller invokes an API. The API begins executing and control is returned immediately to the calling thread, without waiting for the API to finish executing. The calling thread is now free to do other things, while the API does its work. A 'Session ID' is provides as a return value to the calling thread, which uniquely identifies the API invocation that was initiated. The calling application may use the Session ID to listen on a windows event, and be notified when the API finishes executing.

The Adaptiva SDK provides a method for obtaining this Windows event handle. The calling application may also use the Session ID to check if the API has finished executing, and if so, retrieve its return values. The Adaptiva SDK provides a method for this. The return values of each asynchronous API invocation are preserved for up to 5 minutes after it has finished executing, and may be retrieved at any time during that interval. Asynchronous API invocation results are automatically discarded after 5 minutes. Synchronous API invocation results are never cached, and are automatically discarded after the API has finished executing, and results have been returned.

Async = false: API will execute synchronously and wait for the API to complete execution.
Async = true: API will execute and return immediately, without waiting for completion.

 

 

 

Target Machines

Adaptiva client and server APIs can be enabled for local or remote execution while publishing the API.

Local execution:

When the API is invoked on the same machine on which the calling application is running

Remote execution:

When the API is invoked on a different machine than the machine on which the calling application is running

The Adaptiva SDK provides methods which allow the calling process to request invocation of client as well as server APIs, on local machines as well as remote machines. This is accomplished by providing an optional input parameter to the methods provided by the Adaptiva SDK, which specifies the name or IP address of the target machine.

Note: If a NULL or empty string is specified for this input parameter, the API is automatically run on the local machine

 

 

Security for API calls

Adaptiva client and server API calls may be secured by specifying the appropriate security type while publishing the API

No Security:

Any calling application may invoke the API

Password Based Security: 

Any calling application may invoke the API, but it must supply the specified password while invoking the API

[API].SetPasswordSecurity(string password)

Windows User Account Based Security:

Any calling application may invoke the API, but it must supply the specified Windows account and password while invoking the API

[API].SetWindowsSecurity(string sidOrAccountName, string password)

Windows Thread Token Security:

Any calling application running under one of the specified Windows accounts may invoke the API, without needing to specify any additional data while invoking the API

[API].SetThreadTokenSecurity()

HMAC Security:

Any calling application may invoke the API, but it must supply the cryptographic key while invoking the API

[API].SetHMACSecurity(string key)

 

The Adaptiva SDK provides the necessary methods for making use of all of the above security methods.

 

 

Run-Time Considerations

The following DLLs are required at run-time:

• 32-bit AdaptivaApiFoundry.dll: 32 bit Runtime DLL for C, C++, and .NET
• 64-bit AdaptivaApiFoundry.dll: 64 bit Runtime DLL for C, C++, and .NET
• [Optional] .NET .dll: Runtime DLL/assembly for.NET

 

All of the above DLLs are automatically installed as part of the Adaptiva client as well as server installs in the following folders, and therefore never need to be redistributed:

• <installation folder>\BIN\X86: 32-bit AdaptivaApiFoundry.dll
• <installation folder>\BIN\X64: 64-bit AdaptivaApiFoundry.dll
• <installation folder>\BIN\X64: AdaptivaApiFoundryDotNet.dll

 

If you are invoking client or server APIs on the local machine, or from a machine that has either the Adaptiva server or the Adaptiva client installed, you can use the appropriate DLLs which are present under the Adaptiva server or client installation folder

The following Windows environment variables contain the installation path for the Adaptiva server and client respectively:

• %ADAPTIVASERVER%
• %ADAPTIVACLIENT%

These environment variables are automatically created on installation and deleted on the uninstallation of the Adaptiva server and Adaptiva client respectively.

In case neither Adaptiva server nor Adaptiva client is installed on the machine from where the API call is being made, you can distribute the appropriate DLLs from the list above as part of your application, and use them as needed

C and C++ Applications

For applications written in C and C++, either the 32-bit or 64-bit AdaptivaApiFoundry.dll is required at runtime, depending on whether the calling application has been compiled as a 32-bit or 64-bit application. It doesn’t matter whether the Adaptiva client or server are 32-bit or 64-bit versions. No other DLL is required for C and C++ applications. 

.NET Applications

For applications written in C# and other .NET programming languages, the AdaptivaApiFoundryDotNet.dll assembly and either the 32-bit or 64-bit AdaptivaApiFoundry.dll is required at runtime. The AdaptivaApiFoundryDotNet.dll assembly is compiled as 'Any CPU', and the same assembly will support .NET applications compiled for 'Any CPU' and 64-bit platforms. 

In both cases, it doesn’t matter whether the Adaptiva client or server are 32-bit or 64-bit versions. No special efforts are needed to load the appropriate DLL. During installation of the Adaptiva client and server, Windows is automatically configured so that it will find and load the correct version of the DLL automatically when your application is launched

For loading the assembly, the application will have to specify the appropriate paths where the assembly is located

 

 

Using the Adaptiva SDK with C and C++

Please refer to the attachment 'C and C Samples.zip' which can be downloaded from the link at the bottom of this article. This zip file contains the following files:

Source Code Samples written in C/C++:

• HelloClient.c, HelloClient.cpp
• Async.c, Async.cpp
• CommandLine.c, CommandLine.cpp

 

Source Files and Header Files for C/C++ Applications:

• AdaptivaApiFoundry.h: header file for C, C++
• AdaptivaApiFoundryCpp.h: header file for C++
• AdaptivaApiFoundryCpp.cpp: source file for C++

 

The samples have been developed to demonstrate the input validation, return value validation, and memory cleanup that should be performed while writing production code. Some of these steps may be left out for experimental code and test code:

1. #include the header file AdaptivaApiFoundry.h in your project. In case you’re using Visual Studio, and are using pre-compiled headers, this header file is best included in your project’s stdafx.h file. Otherwise, it may need to be included in all your source files which make use of the methods and data types provided by the Adaptiva SDK
   
   
2. Microsoft’s 'windows.h' header file also needs to be included. Some additional Microsoft header files may also need to be included. These are all part of various Microsoft SDKs, and are readily available
   
   
3. Add the import library X32\AdaptivaApiFoundry.lib or X64\AdaptivaApiFoundry.lib as a linker input file in your project, depending on whether you’re compiling for 32-bit or 64-bit platforms
   
   
4. During debugging, copy the X86\AdaptivaApiFoundry.dll or X64\AdaptivaApiFoundry.dll file into the output folder where the compiler creates the debug version of your EXE file, depending on whether you’re compiling for 32-bit or 64-bit platforms. This will help your debugger quickly find and load the appropriate DLL when you launch your application under the debugger
   
   
5. If you expect that your application may need to make remote Adaptiva server or client API calls from a machine on which neither Adaptiva server, not Adaptiva client have been installed, then you must redistribute the X86\AdaptivaApiFoundry.dll or X64\AdaptivaApiFoundry.dll file, depending on whether you’re compiling for 32-bit or 64-bit platforms. The appropriate DLL is best copied into the same folder where your application’s main EXE file exists. Copying the DLL during your application’s installation is sufficient, no special DLL registration etc. is required.
   
   
6. For C++ applications only:
   1. #include the AdaptivaApiFoundryCpp.h file into stdafx.h file, and other source files as needed
      
      
   2. Also include the AdaptivaApiFoundryCpp.cpp source file for C++ into your project. To simplify integration, the C++ part of the SDK has been provided as source code instead of a separate DLL
      
      
   3. Including the source code will statically link the tiny C++ SDK into your application directly

 

 

Using the Adaptiva SDK with C# and other .NET Programming Languages

Please refer to the attachment '.NET Samples.zip' which can be downloaded from the link at the bottom of this article. This zip file contains the following files:

Source Code Samples written in C#:

• HelloClient.cs
• Async.cs
• CommandLine.cs

 

Source Files and Header Files for C/C++ Applications:

• cs: dummy stub file for C#

 

The samples have been developed to demonstrate the input validation, return value validation, and memory cleanup that should be performed while writing production code. Some of these steps may be left out for experimental code and test code

1. Add the Adaptiva .NET SDK assembly as a reference in your project by browsing to the AdaptivaApiFoundryDotNet.dll file provided in the SDK, and adding it
   
   
2. Add a 'using AdaptivaApiFoundry;' statement to the beginning of your source files which will be invoking the Adaptiva APIs. This is the namespace used by the Adaptiva SDK classes
3. During debugging, copy the X86\AdaptivaApiFoundry.dll or X64\AdaptivaApiFoundry.dll file, as appropriate, and the AdaptivaApiFoundryDotNet.dll file into the output folder where the compiler creates the debug version of your EXE file. This will help your debugger quickly find and load the appropriate DLLs when you launch your application under the debugger
   
   
4. If you expect that your application may need to make remote Adaptiva server or client API calls from a machine on which neither Adaptiva server, not Adaptiva client have been installed, then you must redistribute the X86\AdaptivaApiFoundry.dll or X64\AdaptivaApiFoundry.dll file, as appropriate, and the AdaptivaApiFoundryDotNet.dll file. The appropriate DLLs are best copied into the same folder where your application’s main EXE file exists

Copying the DLL during your application’s installation is sufficient, no special DLL registration etc. is required.

 

 

The HelloServer and HelloClient Sample APIs

The HelloServer and HelloClient APIs are built into the Adaptiva server and Adaptiva client, respectively. Both APIs can be invoked on local or remote client and server machines, synchronously and asynchronously, without any password or security. This allows SDK integration code to be tested easily

Input parameters

Message:

This input parameter is echoed back in the 'ResultText' return value, and helps validate that parameter passing and return value extraction code is working end to end

Delay:

This input parameter specifies the amount of time in milliseconds that the API should consume before it finishes executing. This allows asynchronous execution to be tested, by letting you control how much time the API takes before it finishes executing

 

Return values

The API returns the following values, which have been selected to be easy to remember and validate, without constantly referring to this document.

 

ResultBoolean	true
ResultText	[Echos the value passed in the 'Message' input parameter]
ResultWholeNumber	123456789123456789
ResultFractionNumber	123456789.123456
ResultDateTime	4th July 2017, 4:4:4:.444AM
ResultArrayOfBoolean	{true, false, true, false}
ResultArrayOfText	{"Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine" }
ResultArrayOfWholeNumbers	{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 123456789123456789}
ResultArrayOfFractionalNumbers	{1.1, 22.22, 333.333, 4444.4444, 55555.55555, 666666.666666, 123456789.123456}
ResultArrayOfDateTime	{1/1/2017 1:1:1.111 AM, 2/2/2017 2:2:2.222 PM, 3/3/2017 3:3:3.333 AM, 4/4/2017 4:4:4.444 PM, 5/5/2017 5:5:5.555 AM, 6/6/2017 6:6:6.666 PM, 7/7/2017 7:7:7.777 AM, 8/8/2017 8:8:8.888 PM, 9/9/2017 9:9:9.999 AM}

 

 

 

The HelloClient Sample

This sample synchronously invokes the HelloClient client API, on the local machine, and displays the results to the console

Default input parameters

Message: Hello World!

Delay: 1 second

It then displays results of the API call

 

 

The Async Sample

This sample asynchronously invokes the HelloServer server API, on a remote server whose name or IP address has been specified on the command-line.

The API is invoked with a delay of 23 seconds, to highlight how asynchronous API execution can benefit the application while invoking those APIs that perform a lot of work and take a long time to complete.

After invoking the API, the sample checks the execution status of the API call after every 10 seconds.

The sample also detects completion of the API using a Windows event notification, so that it can immediately abort its 10-second wait as soon as the API finishes executing.

 

 

The CommandLine Sample

This sample implements a tool that can be used for making synchronous or asynchronous calls to any client or server API, to any local or remote client or server machine, from the command-line, without recompiling the code.

In addition to being a sample that illustrates coding techniques for invoking Adaptiva APIs, this tool is also very useful for quickly testing the behavior of any Adaptiva client of server APIs, without having to write test code for each API

 

For a full guide into getting started with the API Foundry/SDK and stepping through the creation of a simple example, please refer to this guide.