Adding New Extensions
Step 1: Develop the C Custom Extension Code
This section describes what is involved in coding a custom extension for use within the Business Modeler Framework (BMF). The example referenced here is used in the implementation illustration in the following section. This custom extension initiates a workflow process on an item revision (after it is created) when creating an item.
This is custom code developed using standard ITK development practices.
#ifndef BMF_SAMPLE_C_2
#define BMF_SAMPLE_C_2
#include "bmf_extension_utils.h"
#include <epm.h>
#include <bmf.h>
#include <libuserext_exports.h>
extern USER_EXT_DLL_API int
bmf_extension_workflow_sample(METHOD_message_t* msg,
va_list args);
#include <libuserext_undef.h>
#endif // BMF_SAMPLE_C_2
Figure 7-2. bmf_extension_workflow_sample.h Include File
Chapter 7 System Administrator
• #include bmf.h
Contains the structure definition (BMF_extension_arguments_t) needed for processing user parameter data. This is processed as an array of these structures by the developer.
Contains the value of theName field entered by the administrator in the Parameter Details dialog window when defining the extension through the Business Modeler application (see the example inStep 3: Implement the C Custom Extension). In the example, there are two: Release Process and Company ID.
val_union
Contains the actual value defined for the specified paramName when the administrator assigns the extension to an entry point in theArgument Panel for extension on the Assign Extension tab (made up of only one of the three value definitions at one time based on the type of value). In the example, Release Process is a mandatory String, and Company ID is an optional Integer. A mandatory value is always present. An optional value may or may not be present.
Contains the ITK function definition (BMF_get_user_params defined in the bmf.h file) needed for retrieving the user parameter data of the custom extension. This ITK function returns a row count and an array of all the existing user parameter name/value pairs (using the BMF_extension_arguments_t structure described above) from the input METHOD_message_t structure.
This array of structures needs to be freed by the ITK developer using a call to the MEM_free function.
• #include libuserext_exports.h
Contains definitions needed for processing.
• #include libuserext_undef.h
Contains the symbol definition processing required for the user extension API.
System Administrator
• Any additional #include lines that need to be defined for the custom extension based on functionality. In the sample, the epm.h file is needed because of the workflow processing functionality it is using.
• USER_EXT_DLL_API
extern USER_EXT_DLL_API custom-extension-function
Prototype for each function that is created as a custom extension. In the example, there is only one:
extern USER_EXT_DLL_API
bmf_extension_workflow_sample(
METHOD_message_t* msg,
va_list args);
All functions used as custom extensions must be defined this way.
The user parameters for the custom extension are stored in the message structure (msg parameter) and retrieved by the BMF_get_user_params function.
va_list contains the arguments for the current operation.
Chapter 7 System Administrator
if (iman_strcmp(paramName, p[i].paramName) == 0) {
char job_desc[WSO_desc_size_c + 1] = {’\0’};
char job_name[WSO_name_size_c + 1] = {’\0’};
tag_t job_tag = NULLTAG;
Figure 7-3. bmf_extension_workflow_sample.c Source File (Continued)
System Administrator
/********************/
/* Initialization */
/********************/
//Get the parameters from the ITEM_create_msg item_id = va_arg( args, char *);
item_name = va_arg( args, char *);
type_name = va_arg( args, char *);
rev_id = va_arg( args, char *);
new_item = va_arg( args, tag_t *);
new_rev = va_arg( args, tag_t *);
item_tag = *new_item;
rev_tag = *new_rev;
// Extract the user arguments from the message
ifail = BMF_get_user_params(msg, ¶mCount, &input_args);
if (ifail == ITK_ok && paramCount > 0) {
index = getArgByName(input_args, paramCount, "Release Process");
if (index != -1) {
iman_strcpy(relproc, input_args[index].arg_val.str_value);
}
index = getArgByName(input_args, paramCount, "Company ID");
if (index != -1) {
companyid = input_args[index].arg_val.int_value;
}
MEM_free(input_args);
Figure 7-3. bmf_extension_workflow_sample.c Source File (Continued)
Chapter 7 System Administrator
"Auto initiate job for item/rev (%s/%s-%d)", item_id, rev_id, companyid );
//Get the template tag.
ifail = EPM_find_template(relproc , 0, &template_tag);
if (ifail != ITK_ok) {
return ifail;
}
// Create the job, intiate it and // attach it to the item revision.
attachment_type = EPM_target_attachment;
} /* end of function - bmf_extension_workflow_sample */
Figure 7-3. bmf_extension_workflow_sample.c Source File
System Administrator
• #include custom *.h file described above In the example, it is as follows:
#include bmf_extension_workflow_sample.h
• Any source code functions that need to be written to support the custom extension based functionality. In the sample, there are two functions:
int getArgByName(
BMF_extension_arguments_t* p,
int arg_cnt,
const char* paramName)
Given the user arguments returned by the call to the BMF_get_user_params function, return the index in the user argument array based on the input parameter name string.
Any optional parameters for which no value was specified is not present in the data array, so this function returns a –1.
int bmf_extension_workflow_sample(
METHOD_message_t* msg,
va_list args);
Retrieve the message parameters for the current operation using va_arg.
In this example, the current operation is ITEM_create_msg. So there are four character string (pointers) and two tag_t pointers to retrieve. This data represents item ID, item name, type name, revision ID, new item, and new revision, respectively.
Retrieve the custom extension parameters from the user parameters of the message using the BMF_get_user_params function. In this example, the custom extension is bmf_extension_workflow_sample. So there is one mandatory character string value and one optional integer value to retrieve.
This data represents Release Process and Company ID, respectively.
• Process each of the individual extension parameters that have been retrieved into the array of BMF_extension_arguments_t structures.
Call the getArgByName local function to retrieve the appropriate value for each data element and assign it to the appropriate variable.
The source code needs to be able to handle optional parameters that were not assigned on a particular extension point.
• Now all of the data from the message and from the custom extension should be available to you. Write the rest of the ITK functionality to accomplish the goal.
Chapter 7 System Administrator
Keep in mind the following:
• An extension should be expected to process one message.
• The message data and custom extension user data are independent of each other so it does not matter which is processed first. However, they should be processed together as a set.
• You are expected to know the data that exists for the message. This includes data types and the retrieval order so this data can be processed properly using va_arg.
• You are expected to know the user data that exists for the custom extension. This includes data types and whether each data element is mandatory or optional so that this data can be processed properly after the BMF_get_user_params function is used to retrieve this data.
• Several extensions can be compiled into the same library.
– Copy all the implementation C files to the same directory.
– Use the compile scripts (discussed below) and specify multiple targets to be compiled.
– Execute the link script once to produce the library containing these extensions.