Programming Guides › Programming Guide for C › DMS Workflow API

DMS Workflow API

This section contains the following topics:

DMS Workflow API Overview

Using the DMS Workflow API, you can add simple pre- and postprocess workflow for DMS events. To implement these processes, you must:

Develop a shared library that supports the DMS Workflow API and provides the custom functionality you need. The shared library must contain the workflow functions defined as exportable symbols.
SmApi.h defines all of the data structures necessary to create custom workflows. SmEventApi.h defines all of the workflow events.
Install the shared library in one of the following locations:
- On UNIX platforms, in the SiteMinder lib directory
- On Windows platforms, in the SiteMinder bin directory
Define the workflow library in the Administrative UI. Every DMS Administration realm and every resource realm into which an end-user may self-register is associated with a Registration Scheme. The Registration Scheme Properties UI contains a text field where you may enter the name of the shared library to use for DMS workflow.

Note: The DMS API (available in Java only) has different functionality than the DMS Workflow API (available in C/C++ only). The DMS API lets you develop directory management applications that perform similar operations as the SiteMinder DMS product. The DMS Workflow API works in conjunction with DMS and fires when certain pre-process and post-process DMS events occur, allowing you to develop applications that perform additional functionality before and/or after these events.

DMS Sessions

A user working with a DMS application is assigned a session to maintain the application context according to the user’s administrative privileges.

There are two types of DMS user sessions:

An Administration session is created for a user who has administrative privileges in the DMS application. In order to start a DMS session, the user must be authenticated and authorized to use the application. Administrative sessions generate events which are categorized as administrative events. Such events provide a user context to the workflow libraries.
Registration sessions are created for registration realms where users will be adding themselves to the directory. A registration session is created for a realm upon the first request to self-register for the resources in that realm. The session remains live on the DMS server until SiteMinder is shut down. Registration sessions generate events that are categorized as registration events. Such events will not provide a user context to the workflow libraries. Registration events are limited to the creation of a user entry and the self-modification of a user entry.

DMS Workflow

When a user initiates a DMS session, either by requesting self-registration or by entering a DMS administration application, the following SiteMinder objects are located:

The realm of the requested resource. For self-registration, this is the realm containing the page for which the user is signing up. For DMS administrators, the realm is the location of the DMS Administration servlet. The realm is obtained by the SiteMinder Web Agent when the user requests access.
The registration scheme associated with the realm. The registration scheme contains the name of the workflow library, if any.
Because workflow is associated with a realm, it is possible to set up several workflow libraries, depending on the desired DMS event processing for a particular resource. For example, self-registration may be required in order to receive documents on separate sites, but the rules for pre- and postprocessing users for each site may be different.

For example, it is possible to set up a number of self-registering sites; each may have its own workflow library.

If the registration scheme includes a workflow library name, the library is loaded. The loader checks to see that all the required functions are exported by the library. If the library can not be loaded or a function is missing, session initialization will fail and DMS requests for that realm will not be processed. To correct this situation:

Make sure the library has been installed in the correct location, as specified in DMS Workflow API Overview.
Ensure that the required functions are exported by the library.
If desired, disable the workflow by removing the library name from the registration scheme, using the Administrative UI.

When the workflow library is loaded, it will be called for every DMS event that involves adding, modifying, or deleting entities in the user directory during the session.

Workflow Events

Workflow events are documented in EMS Event Type. These events are used for logging as well as for workflow. Events are divided into these categories:

SmLogEmsCat_DirectoryUser. Assigned to events generated by an end-user, such as self-registration and modification.
SmLogEmsCat_DirectoryAdmin. Assigned to events generated by a DMS administrator.
SmLogEmsCat_DirectorySession. Assigned to events associated with DMS session management.
SmLogEmsCat_EventPreprocess. Assigned to events generated by a workflow preprocess step; used for logging the result of a workflow event.
SmLogEmsCat_EventPostprocess. Assigned to events generated by a workflow postprocess step; used for logging the result of a workflow event.

More Information:

EMS Event Type

Preprocess Events

A preprocess event takes place before the DMS request is processed. A workflow library may evaluate the request and decide whether to accept or reject it. If accepted, the request will be carried out. If rejected, the request will not be carried out and a preprocess error will be returned to the DMS application. The preprocess function may optionally set an error message for DMS to display to the user.

The workflow library is called to preprocess all events in the categories SmLogEmsCat_DirectoryUser and SmLogEmsCat_DirectoryAdmin.

Postprocess Events

A postprocess event takes place after the DMS request is successfully processed. A workflow library may evaluate the request, take any action as dictated by the business process, and return success or fail status. The postprocess function may optionally set an error message for DMS to display to the user. It is important to note that postprocess failure will not result in rolling back the transaction. Unacceptable requests should be detected in preprocessing.

The workflow library is called to postprocess all events in the SmLogEmsCat_DirectoryUser and SmLogEmsCat_DirectoryAdmin categories, as well as the SmLogEmsCat_DirectorySession category. This last category provides session status only.

Write and Define a DMS Workflow

To create a custom workflow library:

Include the SmApi.h file, as follows:
```
#include "SmApi.h"
```
Include the SmEventApi.h file, as follows:
```
#include " SmEventApi.h"
```
Make sure the following functions are externally visible:

Function	Description
SmDmsWorkflowInit()	Initializes the workflow library. The library should initialize whatever resources it needs at this time.
SmDmsWorkflowPostprocess()	Performs the workflow postprocess step.
SmDmsWorkflowPreprocess()	Performs the workflow preprocess step.
SmDmsWorkflowRelease()	The library should release whatever resources were created by initialization at this time.

Each entry point in the shared library must be defined according to specified syntax.

Note: If you are using Microsoft Visual Studio, export the function addresses to a modular definition file (.DEF) file. To export the function addresses, create a .DEF file. In the file’s export section, list all the functions described in the previous table. Once you have created the .DEF file, add it to the Microsoft Visual Studio project.

Compile the code into a DLL or shared library. The name of this file will be specified as the library in the SiteMinder Registration Properties dialog.

When you have written a custom workflow, such as the example provided at the end of this chapter, you must define the workflow in the Registration Properties dialog using the Administrative UI.

Sm_Api_DmsContext_t

This structure provides DMS-specific context.

Syntax

typedef struct
{
   unsigned char        bIsUserContext;
   char*                lpszAdminUserName
   char*                lpszAdminUserPath;
   char*                lpszDirPath;
   void                 lpReserved1;
   char*                lpszDirServer;
   char*                lpszDirNamespace;
   char*                lpszSessionId;
   void*                lpDirParam;
   void*                lpAdminParam;
   Sm_Api_GetUserProp   fGetAdminProp;
   Sm_Api_GetDmsDnProp  fGetDnProp;
} Sm_Api_DmsContext_t;

Field	Description
bIsUserContext	Flag indicating that SiteMinder has established the user's identity and stored it in lpszAdminUserName. When this flag is set, the function referenced in fGetAdminProp can be used to obtain properties of this user.
lpszAdminUserName	The DMS administrator user name. This will be a full distinguished name for Administrator events, else it will be an empty string.
lpszAdminUserPath	The DMS administrator user path in the SiteMinder notation, for Administrator events only.
lpszDirPath	Directory path, in the SiteMinder notation, of a SiteMinder user directory specified by the registration scheme.
lpReserved1	Reserved for internal use.
lpszDirServer	The directory server of a SiteMinder user directory specified by the registration scheme.
lpszDirNamespace	The directory namespace.
lpszSessionId	The DMS session ID.
lpDirParam	Pointer to the parameters to be passed to fGetDnProp.
lpAdminParam	Pointer to the parameters to be passed to fGetAdminProp.
fGetAdminProp	Function that returns attributes of the administrative user. The calling syntax for this function is: int nMaxBufSize = 256; char lpszResult[256]; int nBuflen = lpDmsContext->fGetProp ( lpDmsContext->lpAdminParam, "mail", nMaxBufSize, lpszResult); If the function succeeds, the return value is the number of bytes in the output buffer. If the function fails, the return value is -1.
fGetDnProp	Function that returns attributes given a distinguished name. Any object may be examined as long as it can be retrieved from the directory server. The calling syntax for this function is: int nMaxBufSize = 256; char lpszResult[256]; char lpszDn[] = "uid=jsmith,ou=People,o=dms.com"; int nBuflen = lpDmsContext->fGetProp ( lpDmsContext->lpDirParam, lpszDn, "mail", nMaxBufSize, lpszResult); If the function succeeds, the return value is the number of bytes in the output buffer. If the function fails, the return value is -1.

Function Declarations

In structure Sm_Api_DmsContext_t, the functions fGetAdminProp and fGetDnProp are declared in SmApi.h as follows:

fGetAdminProp

typedef int (SM_EXTERN *Sm_Api_GetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf   /* Output buffer to hold the user property */
);

fGetDnProp

typedef int (SM_EXTERN *Sm_Api_GetDmsDnProp)
(
const void* lpParam,       /* The function parameter */
const char* lpszDN,        /* The DN of the object */
const char* lpszPropName,  /* Object property name (null-term) */
const int nBytesValueBuf,  /* Max size of object property buffer */
char* lpszValueBuf  /* Output buffer to hold the object property */
);

Sm_DmsWorkflow_Attribute_t

This structure pairs a request or response attribute name with a string representation of the attribute value. An array of these structures is used to represent a DMS request to create or modify a directory object.

Syntax

typedef struct
{
   const char* lpszAttrName;
   const char* lpszAttrValue;
} Sm_DmsWorkflow_Attribute_t;

Field	Description
lpszAttrName	Name of the request or response attribute.
lpszAttrValue	String representing the attribute value.

SmDmsWorkflowInit()

SiteMinder calls this function so that a workflow library can perform its own initialization procedure. This call is made once, when the library is loaded for the first time.

Syntax

Sm_DmsWorkflowApi_Status_t SM_EXTERN SmDmsWorkflowInit();

Returns

Sm_DmsWorkflowApi_Success. Function was successful.
Sm_DmsWorkflowApi_Failure. Function was not successful, and the workflow will not be loaded. If the workflow is not loaded successfully, DMS events that depend on the registration scheme that specified the workflow will fail until:
- The workflow library can load successfully
- The workflow library is removed from the registration scheme

SmDmsWorkflowPostprocess()

SiteMinder calls this function so that a workflow library can postprocess a DMS event.

Syntax

Sm_DmsWorkflowApi_Status_t SM_EXTERN SmDmsWorkflowPostprocess(
   const Sm_Api_Context_t*            lpApiContext,  
   const Sm_Api_DmsContext_t*         lpDmsContext,
   const char *                       lpszWorkflowOid,
   const int                          nCategoryId,
   const int                          nEventId,
   const char *                       lpszObjectPath,
   const int                          nAttributes,
   const Sm_DmsWorkflow_Attribute_t*  pAttributes,
   const int                          nBytesErrMsg,
   char *                             lpszErrMsg
);

Parameter	I/O	Description
lpApiContext	I	Pointer to the API context structure.
lpDmsContext	I	Pointer to the DMS context structure.
lpszWorkflowOid	I	Unique workflow identifier.
nCategoryId	I	DMS event category.
nEventId	I	DMS event identifier
lpszObjectPath	I	Distinguished name of the object that is the target of this event, if any. The target object DN will be available for requests to create, delete, and modify directory objects.
nAttributes	I	Number of attributes in the array of response attributes.
pAttributes	I	Array of DMS response attribute/value pairs.
nBytesErrMsg	I	Maximum size of the output error buffer.
lpszErrMsg	O	Output buffer to receive the error text. Use this buffer to return an error message to the DMS application.

Returns

Sm_DmsWorkflowApi_Success. Function was successful.
Sm_DmsWorkflowApi_Failure. Function was not successful.
Sm_DmsWorkflowApi_Ignore. The event was of no interest to this step.

Remarks

The event has already been processed. Return values of Sm_DmsWorkflowApi_Success or Sm_DmsWorkflowApi_Ignore result in a success status returned to the application. Sm_DmsWorkflowApi_Failure causes an error code to be returned to the application. The error code indicates that there was a failure in the DMS postprocessing step.

The character array lpszErrMsg may be used by the postprocess function to send an error message back to the application. The maximum size of the character array is specified in nBytesErrMsg.

SmDmsWorkflowPreprocess()

SiteMinder calls this function so that a workflow library can preprocess a DMS event.

Syntax

Sm_DmsWorkflowApi_Status_t SM_EXTERN SmDmsWorkflowPreprocess(
   const Sm_Api_Context_t*             lpApiContext,  
   const Sm_Api_DmsContext_t*          lpDmsContext,
   const char *                        lpszWorkflowOid,
   const int                           nCategoryId,
   const int                           nEventId,
   const char *                        lpszObjectPath,
   const int                           nAttributes,
   const Sm_DmsWorkflow_Attribute_t*   pAttributes,
   const int                           nBytesErrMsg,
   char *                              lpszErrMsg
);

Parameter	I/O	Description
lpApiContext	I	Pointer to the API context structure.
lpDmsContext	I	Pointer to the DMS context structure.
lpszWorkflowOid	I	Unique workflow identifier.
nCategoryId	I	DMS event type.
nEventId	I	DMS event identifier
lpszObjectPath	I	Distinguished name of the object that is the target of this event, if any. The target object DN will be available for requests to create, delete, and modify directory objects.
nAttributes	I	Number of attributes in the array of request attributes.
pAttributes	I	Array of DMS request attribute/value pairs.
nBytesErrMsg	I	Maximum size of the output error buffer.
lpszErrMsg	O	Output buffer to receive the error text. Use this buffer to return an error message to the DMS application.

Returns

Sm_DmsWorkflowApi_Success. Function was successful.
Sm_DmsWorkflowApi_Failure. Function was not successful.
Sm_DmsWorkflowApi_NoUserContext. An administrative user event was generated and the user context could not be determine.
Sm_DmsWorkflowApi_SkipSuccess. The event will be handled by the preprocess function and no further processing is desired.
Sm_DmsWorkflowApi_Ignore. The event was of no interest to this step.

Remarks

A return of Sm_DmsWorkflowApi_Success or Sm_DmsWorkflowApi_Ignore causes processing to continue. Any other return causes processing to stop, and an error code is returned to the application. The error code indicates that there was a failure in the DMS preprocessing step.

Sm_DmsWorkflowApi_SkipSuccess causes processing to stop, but a success status is returned to the application. It is up to the implementation of the preprocess function to fulfill the desired goal. If the function fails, it should return a failure code rather than Sm_DmsWorkflowApi_SkipSuccess.

The character array lpszErrMsg may be used by the preprocess function to send an error message back to the application. The maximum size of the character array is specified in nBytesErrMsg.

SmDmsWorkflowRelease()

SiteMinder calls this function so that a workflow library can perform its own rundown procedure. This call is made once, when SiteMinder is shutting down.

Syntax

Sm_DmsWorkflowApi_Status_t SM_EXTERN SmDmsWorkflowRelease();

Returns

Sm_DmsWorkflowApi_Success. Function was successful.
Sm_DmsWorkflowApi_Failure. Function was not successful.