In this article:
Overview - Overview of the API
Step 1 - Create the workflow to use as the API - Creating the API workflow
Step 2 - Create the Execution Policy - Creating the execution policy to allow remote execution
Step 3 - Call the API from code - Calling the API workflow from managed code
Step 4 - Run the API - Running the API and viewing the results
Overview
In this example, we are going to use a very simple example of creating a new Adaptiva office programmatically outside of the workflow designer. We are going to create a simple console application using C#, pass through the name, description and type of office (Default/WiFi/VPN) and return the result. In case the office already exists, or an unknown error occurs we will return data pertaining to the issue.
Step 1 - Create the workflow to use as the API
Any workflow can be used as an API but a workflow should adhere to these basic principals:
1) If the API is a client-side API the workflow must be a client workflow
2) If the API is to perform server-side activities, the workflow must be either a server workflow or a business workflow. It is recommended to use a business workflow.
For this example, because the workflow is going to create an office on the AdaptivaServer, we will create a business workflow.
The basic workflow outline looks like this:
The activities that we will be using are as follows:
| Try | Try-Catch | The Try, MainTry and CatchErrors nodes are all part of the Try-Catch activity which will catch any unhandled errors that may occur during workflow execution. |
| ReturnError | Empty | The ReturnError node will set the output properties to return the error caught by the Try-Catch. |
| IfAllPropertiesSpecified | If-Else | The purpose of this IF statement is to check whether all properties have been passed into the workflow |
| FindOfficeByName | OfficeSearch | We use an OfficeSearch activity to check whether the office already exists |
| IfExists | If-Else | We check the result of FindOfficeByName to see if the office exists |
| CreateOffice | OfficeCreator | We create a new office object using the OfficeCreator activity |
| SaveOffice | OfficeCreator | This activity is used to save the new office object |
| IfSavedSuccessfully | If-Else | The purpose of this IF statement is to check whether the office saved successfully |
Stepping Through
Activity 1: Start1
The Start1 activity is the built-in activity and holds the input values. On the Start1 node we have created 3 user-defined properties which will act as the input properties for our API. These are:
1) OfficeName [The name of the office that will get created by the API]
2) OfficeDescription [The description to give the office object that gets created by the API]
3) OfficeType [The type of the office that will get created. Can be one of: Default, WiFi or VPN]
Activity 2: Try
This Try-Catch activity consists of 3 nodes - Try, MainTry and CatchErrors. It does not take any input properties and will simply catch any unhandled errors that occur in any of it's contained activities.
All subsequent activities are placed inside the Try-Catch activity.
Activity 3: ReturnError
This Empty activity will be used to set the ResultText and ResultBoolean nodes of the End1 node using the external node property setter in the event that an unhandled error occurs during execution. This node will only run if the previous Try-Catch catches an error.
Activity 3: IfAllPropertiesSpecified
This If-Else activity is used to check if all input properties have been specified. We want to make sure that an office name, description and type have all been passed in. The If Statement has the following condition:
Start1.OfficeName != null && Start1.OfficeDescription != null && Start1.OfficeType != null
True1: If the IfAllPropertiesSpecified condition returns true then execution passes to the next activity. This indicates that all input properties were specified.
False1: If the IfAllPropertiesSpecified condition returns false then one or more input properties were missing and on the False1 step we set the ResultBoolean and ResultText properties of the End1 node, to tell the workflow to return a predefined error and to indicate API execution failure.
Activity 4: FindOfficeByName
The FindOfficeByName node uses an OfficeSearch activity and the operation 'Find Office by name'.
The name is passed through from the OfficeName property on the Start1 node.
Activity 5: IfExists
This If-Else activity is used to check if the FindOfficeByName node returned a valid office object. If it did, then that would indicate that the office already exists. If this is the case we don't need to continue workflow execution and an error should be returned that indicates that the office the API is being asked to create is already present.
The condition for this If-Else statement is:
FindOfficeByName.Result
True2: If the IfExists condition returns true then the office already exists. In this case, the True2 node will set the ResultText and ResultBoolean properties of the End1 node to tell the API to return a failure and appropriate text to indicate the existence of the office.
False2: If the IfExists condition returns false then execution passes to the next activity. This indicates that the office could not be found and so should be created.
Activity 6: CreateOffice
This OfficeCreator activity uses the 'Create Office' operation to create an office with the specified Name, Description and Type. The values for these fields are passed through from the input properties specified on the Start1 node.
Note: This activity also supports setting other properties such as 'Metered' and 'AllowDirectCDN' but for this example we will not be setting these.
This node has a single output property, OfficeObject, which will contain the office object that we will work with later.
Activity 7: SaveOffice
With the office object created we now need to save it. We use the 'Save Office' operation of the OfficeCreator activity to perform this save. This operation only takes a single input property, a JAVA OBJECT type representing the office object. We specify the office object that was returned by the CreateOffice activity for this.
This activity will return 3 output properties:
1) OfficeId: The ID of the newly created and saved office.
2) Result: A true or false boolean indicating whether the Save operation was successful.
3) ErrorDescription: In the event that the Save operation was not successful, this property contains the error that was returned.
Activity 8: IfSavedSuccessfully
This If-Else activity is used to check the result of the SaveOffice activity. If the office saved successfully then we can return API success. If the Save operation failed to save the office, we need to return an API failure and the error message that was returned by the activity.
The condition for this If-Else statement is:
SaveOffice.Result
In either case, true or false, we want to return the result to the calling application.
True3: If the IfSavedSuccessfully condition returns true then the API has successfully performed the task it was supposed to and so returns a success result boolean and text back to the calling application.
False3: If the IfSavedSuccessfully condition returns false then the save operation failed and so the API must return a false boolean to indicate API failure and the description of the error that was returned as the result text.
Activity 9: End1
The End1 node will terminate the workflow and use the values that have been set in previous activities using the External Node Property Setter to return the ResultText and ResultBoolean.
The ResultBoolean initial value has been set to True so that if the workflow executes all the way through without error and without the value of ResultBoolean being set by the external node property setter on any previous activity, it will return a success code instead of failure. All paths in this workflow however, will set this value from a previous activity.
Once the workflow is complete we need to save and deploy it. Right-click on either the workflow itself in the Workflow Explorer, or anywhere in whitespace on the Workflow canvas and choose 'Save and Deploy' (alternatively, select Save, and then select Deploy).
When the Deploy dialogue box appears, optionally choose to enable Logging, set your max logfile size and verbosity, then click OK.
Step 2 - Create the Execution Policy
After we've created our workflow we need to tell the AdaptivaServer to allow remote execution requests. At this point, although we have a workflow, it cannot be launched programmatically until we authorise it using an execution policy.
In the workbench, navigate to Misc > Tool Foundry Perspective.
We then need to create either a Client Workflow Execution Policy or a Server Workflow Execution Policy, depending on whether we are using a Client Workflow or a Server/Business workflow.
For this example, we have created a Business workflow, so choose 'Create Server Workflow Execution Policy' from the Tool Foundry Task Navigator.
In the view that appears, either drag a server workflow into the 'Server Workflow' box, or click the Add button to the right of the box and select the Workflow. Here we will select the Adaptiva API - Create Adaptiva Office workflow and then click Save and choose a location to Save the execution policy.
Note: It is also possible to give the workflow an execution password that must be specified in order for this workflow to be launched externally. We won't require a password for this example.
At this point, the API is ready and can be launched through code.
Step 3 - Call the API from code
In this example we're going to create a new C# console application using Microsoft Visual Studio. We start by creating our project.
We then need to add a reference to the .NET DLL (AdaptivaApiFoundryDotNet.dll)
We will also need the core library file (AdaptivaApiFoundry.dll), written in C++. This cannot be added a reference however, but can be added as a resource file or simply copied manually into the output directory. This must be present in the same directory as the compiled executable in order to invoke the API. Additionally, this is architecture specific so the correct version of the AdaptivaApiFoundry.dll needs to be used depending on whether the operating system is 32-bit or 64-bit.
We can then add a using statement at the top to include the use of the resource in the class, and then we can start adding our code. (1)
The first thing we're going to want to do is prompt for the input of the 3 properties that will get input to the API (and passed into the workflow as user-defined properties on the Start1 node). (2)
We will generate console prompts and input capture code for the 3 properties as below:
Console.WriteLine("Please enter an office name:");
string OfficeName = Console.ReadLine();
Console.WriteLine("Please enter an office description:");
string OfficeDescription = Console.ReadLine();
Console.WriteLine("Please enter an office type (Either: Default, WiFi or VPN):");
string OfficeType = Console.ReadLine();
We are then going to create a new Api object (AdaptivaApiFoundry.Api) and use one of the overloads of the constructor to initialize the object with 3 properties. (3)
1) Server [Boolean]: Whether the API should run on the client or on the server.
2) Async [Boolean]: Whether the API should run asynchronously or not.
3) Target [String]: The machine on which to execute the API.
In the case of the example we shall initialize it as follows:
Api CreateOfficeAPI = new Api(true, false, "EURLABSCCM01.EUR.LAB");
We can then execute the API using the Execute method, return the results and store them in an ApiResult (AdaptivaApiFoundry.ApiResult) object. (4)
The Execute method takes 2 parameters:
1) The name of the API workflow to execute. This must match exactly with the name of the workflow in the Workflow Designer perspective.
2) An array containing the input properties for the workflow. The format for the input property array is <PropertyName>, <PropertyValue>. So for specifying multiple properties, continue appending in this format separated by commas. In this case our workflow takes 3 input properties but the number of properties and their datatype will vary.
In the case of the example we shall call it with the following properties:
ApiResult Result = CreateOfficeAPI.Execute("Adaptiva API - Create Adaptiva Office", new[] { "OfficeName", OfficeName, "OfficeDescription", OfficeDescription, "OfficeType", OfficeType });
Finally, we will access the results and do something with them. In this case we're going to access the ResultText and ResultBoolean properties and simply output them to the console window. After we add another ReadKey() just to stop the console window from closing until we press a key. (5)
Console.WriteLine("ResultBoolean: " + Result.ResultBoolean);
Console.WriteLine("ResultText: " + Result.ResultText);
Console.ReadKey();
The complete numbered code is shown below.
Step 4 - Run the API
After writing our code we can then compile it into an executable and get ready to launch.
In our project, we select Build -> Build Solution from the top toolbar and navigate to the output directory to obtain our compiled executable.
Note: We need to ensure that we build our project for the correct architecture. For 64-bit Operating Systems we must select compile for the x64 platform. For 32-bit Operating Systems we must select compile for the x86 platform. This can be found under the project properties:
We must make sure that there are 3 files together in the same directory before launching the executable.
1) The .exe (in this case CreateOffice.exe)
2) The .NET DLL (AdaptivaApiFoundryDotNet.dll)
3) The core DLL (AdaptivaApiFoundry.dll)
We can then open a command prompt and run the executable.
Network Topology view Before execution:
We are going to create a new office called Paris WiFi (10.100.6.0). It will have the description Paris Wireless Office and the office type will be WiFi.
Running the executable gives us the 3 prompts, we enter the values and we get the results back:
Network Topology View After Execution:
We can see that a new WiFi office has been created with the name and description that was specified. The tool has returned a ResultBoolean of 'True' indicating successful execution and the ResultText 'Office Paris WiFi (10.100.6.0) has been created successfully'.
If we try running the tool again and specify the same name, we see that the tool returns a ResultBoolean of 'False' indicating that the API was not successful and the ResultText gives the reason that the office already exists:
Please check out the other sections to see what other capabilities are possible with the Adaptiva API Foundry and SDK.
The Workflow (Workflow_Adaptiva API - Create Adaptiva Office.obex) used in this example and the sample C# console application project can be downloaded from the link below.
Comments
0 comments
Please sign in to leave a comment.