How to create a Custom Task Template for BI Automation Framework

[TJe]

With BI 4.2 SP05 we have released the BI Automation Framework as part of the BI Administration Console. In this blog I would like to share more Information about the Custom Task Template Java SDK and how you can develop task templates and use them in the Automation Framework.

The Custom Task Template Java SDK allows you - via OSGI Plug-Ins - to add advanced functionality to the Automation Framework. For example you can develop Plug-ins using other APIs of the SAP BusinessObjects Business Intelligence Platform.

This tutorial walks you through the entire process of creating your first Custom Task Template Plug-in using sample content. Prior knowledge of Eclipse and Java is helpful, but not mandatory.  We’ll walk you through the bits that you need to know.

More advanced concepts based on this tutorial:
Use JUnit to simplify the implementation of Custom Task Templates for BI Automation Framework
How to develop and debug a Custom Task Template for BI Automation Framework

We have also published samples you can explore and try:
BI Automation Framework Samples

Creating a Custom Task Template – Getting started

First, we'll prepare the Development Environment. Then show how to modify & deploy the Task Template Definition, deploy the Plug-in and finally use the Custom Task Template in a Scenario.

To learn, how to develop and deploy an easy Custom Task Template sample, you can watch the Video or directly practice the steps as shown below.

Download - Getting Started Video (currently not available)

Prerequisites

• Java Development Kit 7 (or higher) (64-bit), installed


• BI Automation Framework Agent, Archive available
  Installation Package in Folder: ..\Collaterals\Tools\Automation\biaca.zip


• Task Template SDK Sample Projects, Archive available
  Download - Sample Projects (SAP Note - 2626505)

Installing the Eclipse IDE

1. Download Eclipse IDE for Java EE Developers (64 bit) from download.eclipse.org. This edition contains the tools needed to work with the SDK, for example, Plugin Development Tools. Caution Make sure that you only download this Eclipse version. Other versions, especially 32-bit versions, may not work correctly with the Component SDK.


2. Extract the downloaded file to a folder.


3. Locate and run the file eclipse.exe.


4. Create a workspace, for example C:\TaskWriterUtility\workspace.
   The workspace will contain all your SDK projects and the Eclipse IDE settings


5. Close the welcome page.

Importing the Task Template SDK Samples Project

1. Use the Task Template SDK Sample Projects (see Prerequisites)
   The ZIP file contains the sample Eclipse projects you can import to your workspace


2. In the Eclipse IDE select File > Import


3. On the Import Dialog: select General > Existing Projects into Workspace


4. On the Import Projects Dialog: choose the option Select archive file


5. Browse to the location of the ZIP file > select open


6. Select Finish

The sample projects will be listed in your workspace.

Setting the Target Platform

The target platform points to your Agent installation. This enables your Eclipse IDE to access the SDK included with the BI Automation Framework Agent.
You can use an already installed Agent or install the Agent:

1. Go to Collateral\Tools\Automation on the BI platform installation package.


2. Copy and unzip the biaca.zip file to the new Agent's location. Let us assume that you have unzipped the folder at C:\TaskWriterUtility\Agent

After the installation of the Agent, follow these steps:

1. Choose Start Window > Preferences


2. In the Preferences dialog box, choose Plug-In Development > Target Platform


3. Select the checkbox next to the list entry TaskWriter


4. Choose Edit.


5. Choose the Locations tab.


6. Select C:\TaskWriterUtility\Agent\plugins If you have installed the agent to this location you can skip the next step


7. Choose Edit to enter the location of the Agent plugin folder


8. Select Finish


9. Close the Preferences dialog box


10. Project > Clean


11. Choose Clean all projects


12. Choose OK
    This removes all error markers.

Import Launch Configuration to Run TaskWriterUtility command line tool

The first time you deploy a custom task template from your Eclipse IDE, you need to specify some configuration parameters and create a Launch Configuration to run the TaskWriterUtlity command line tool. We will use the configuration files and the launch configuration coming with the samples.

IMPORTANT:
The tools is checking the folder of the template location. Folder must start with 'content/' or must contain '/plugins/task_bundle/'.

• create the folder C:\TaskWriterUtility\workspace\plugins\task_bundle


• Copy the sample from C:\TaskWriterUtility\workspace\com.sap.bong.task.sample\json\sampleTaskTemplate.json to this folder

1. In the Package Explorer open the project TaskWriterUtility


2. Open the file config.properties. You must specify settings of your BI platform and the location of the JSON definition


3. Set values for RESTful_URL, username and password
   RESTful_URL=http://<your server>:6405
   username=<your username>
   password=<your password>


4. The createTaskTemplateLocation1 is set to the folder of the JSON copied from samples
   createTaskTemplatesTotal=1
   createTaskTemplateLocation1=C:\\TaskWriterUtility\\workspace\\plugins\task_bundle\\sampleTaskTemplate.json

The command line tool will write information to the console, so it is important to display the Console view in your Eclipse IDE.

1. Select Window > Show View > Console

Import the Run Configuration.

1. In the Eclipse IDE select File > Import


2. On the Import Dialog: select Run/Debug > Launch Configurations


3. On the next Dialog: select Browse > C:/TaskWriterUtility/workspace/TaskWriter.sample


4. Select TaskWriter.sample and TaskWriterUtilityCLI.launch


5. Select Finish

The Run Configuration is created and available for future use to run the TaskWriterUtility command line tool within Eclipse.

Specify Custom Task Template Definition

To add a custom task template to the Framework, you must provide a JSON definition for your custom task template.

1. In the Package Explorer open the project com.sap.bong.task.sample


2. Open the file sampleTaskTemplate.json located in subfolder json The file contains the task template definitions like name, cuid, description and input & output parameters


3. Important for now is the value for cuid: "generate" Use this value for new task templates to generate a CUID during the deployment. After the deployment you will replace “generate” with the CUID of the created task template InfoObject.

Deploy the Custom Task Template Definition

You can deploy the custom task template definition to the CMS database using the created Run Configuration as follows:

1. Select Run > Run Configurations…


2. Select Java Application > TaskWriterUtilityCLI


3. Choose Run

IMPORTANT:
The Automation Framework service must be running (you can check in the CCM).

The TaskWriterUtility will deploy the definition to your BI platform and you will find some information in the console view, for example the Name, Id and CUID of the custom task template:
First Custom Task (7261, AeGuI0yrcTxLuyCuonSdfK0)

1. Copy the CUID of the custom task template from the Console


2. Replace the value in the file sampleTaskTemplate.json, of your project for example:
   cuid: "generate" with cuid: "AeGuI0yrcTxLuyCuonSdfK0"


3. Save the file.

In the Central Management Console (CMC) you should find the custom task template in:
BI Administration Console > Task Template > Custom

Export and Deploy the Custom Task Template Plug-in to the Agent

1. In the Package Explorer open the project com.sap.bong.task.sample


2. Open the file MANIFEST.MF located in subfolder META-INF. The file contains the plug-in Information.


3. Make sure the Overview tab is displayed


4. Select Export Wizard from the Exporting section


5. Specify the Destination Directory, for example: C:\TaskWriterUtility

Deploy the custom task template plug-in to the Agent of your Server.

1. Browse to the Agent Folder on your sever Installation, for example:
   c:\Program Files (x86)\SAP BusinessObjects\AdminConsole\Agent\plugins\task_bundle


2. Copy the exported plug-in, for example com.sap.bong.task.sample_1.0.0.201711291009.jar from  C:\TaskWriterUtility\plugins to the task_bundle folder

The already started Agent will register the plug-in and you're ready to use the custom task template in the BI Automation Framework. If the plug-in is not registered, please restart the Agent in the Central Configuration Manager (CCM).

Use the Custom Task Template in a Scenario

1. Logon to BI Administration Console


2. Select Automation Framework > Workflow Templates


3. Create a new Workflow Template


4. Drag and Drop Custom > First Custom Task from the Task Templates list to the Canvas


5. Save the Workflow Template for example with name First Custom Task


6. Add a Scenario


7. Drag and Drop Workflow Templates to the Canvas: Logon, First Custom Task, Logout


8. Enter Parameter for Logon, select a Landscape


9. Enter Parameter for First Custom Task, for example:
   Sample Input Parameter = sampleInput
   CSV Parameter (BI 4.2 SP6+) = select Object from Repository Explorer
   CSV Parameter (BI 4.2 SP5) = id,name;100,myDoc;200,testDoc
   The parameter values are just samples and will not be used during execution.


10. Enter Parameter for Logout, select the session


11. Save and Run the Scenario

After the execution of the Scenario, Status should Show Success.

1. Select View Results


2. Check the Summary for the First Custom Task


3. Select Show Details for the First Custom Task

Finally you can check, the Information is reflecting the implementation of the custom task template plug-in.

1. In the Package Explorer open the project com.sap.bong.task.sample


2. Open the file SampleTaskImpl.java


3. Check the method, public String resultSummary()
   contains the text displayed as Summary in View Results


4. Check the method, public String resultDetails()
   contains the CSV text displayed as Summary in Show Details