Create an Example Custom AgileConnector

This topic gives an example of how to create a custom AgileConnector that does custom exception handling in AgilePoint NX.

Create a New Project for the Example AgileConnector in AgilePoint NX Developer

To create a new project for the example CustomExceptionHandler, do the procedure in this topic.

Screen



Prerequisites

Good to Know

Procedure

  1. In Microsoft Visual Studio, click File > New > Project.
  2. On the New Project screen, click AgileConnector.
  3. In the Name field, enter CustomExceptionHandler.
  4. In the Location field, click the Browse, and select the location to create the project.
  5. Click OK.
  6. On the AgileConnector Wizard screen, in the AgileConnector Type field, select Event Listener AgileConnector.
  7. Click Next.
  8. To add sample custom dialog to the project, select Add Sample Custom Dialog.
  9. In the Custom Dialog Type field, select Windows Form (WinForm).
  10. Click Finish.

Configure the Runtime Functionality for an Example AgileConnector

This topic gives an example of how to configure the runtime functionality for an example CustomExceptionHandler AgileConnector with the AgileConnector project template.

Good to Know

  • The AgileConnectorDaemon.cs file has different code for Event Listener Type and Polling Service Type of AgileConnector.
  • Signing an assembly for strong name is done when the AgileConnector project template generates code.
  • To download a sample AgileConnector for custom exception handling, refer to AgileConnector Sample for Custom Exception Handling.

Procedure

  1. In the AgileConnectorDaemon.cs file, replace the default class name MyAgileConnectorDaemon with CustomExceptionHandler.
    [IntegratedApplicationDescriptor(typeof(MyAgileConnectorDescriptor))]
    public class MyAgileConnectorDaemon : WFIntegratedApplication, IWFTrackingEventPublisher
  2. Replace this C# code in Publish method to handle the custom exceptions:
    public void Publish(IWFTrackingEvent evt)
    {
      try
      {
         IWFFaultingExceptionTrackingEvent fault = evt as IWFFaultingExceptionTrackingEvent;
         if (fault == null) return; // in case it is not IWFFaultingExceptionTrackingEvent
    
         DateTime dateOccured = fault.DateOccured;
         Exception e = fault.FaultingException;
    
         // release this object reference immediately when it is done.
         IWFProcessInstance pi = fault.ProcessInstance;
    
      }
      catch (Exception ex)
      {
         Logger.WriteLine("{0}: Error when processing event {1}. Error Message: {2}", 
                           base.AppName, evt.EventName, ex.Message);
      }
    }

Create a .dll File for the Example AgileConnector

To create a .dll file for the example CustomExceptionHandler AgileConnector to deploy in AgilePoint NX, do the procedure in this topic.

Good to Know

  • The deployment package is created with the name [project folder]\bin\ CustomExceptionHandler.dll.

Procedure

  1. In Microsoft Visual Studio, on the Solution Explorer pane, right-click the project name CustomExceptionHandler.
  2. Click Build.

Deploy the Example AgileConnector Package in AgilePoint NX

To deploy a AgileConnector package for the example CustomExceptionHandler connector in AgilePoint NX, do the procedure in this topic.

Screen



Good to Know

How to Start

  1. On the AgilePoint Server machine, in Windows Explorer, right-click the file (AgilePoint Server installation folder) C:\Program Files\AgilePoint\AgilePoint Server\WCFConfigurationUtility.exe, and click Run as Administrator.
  2. On the AgilePoint Server Manager screen, in the left pane, select your AgilePoint Server instance.
  3. Click Open Server Configuration Open Server Configuration icon.
  4. On the AgilePoint Configuration screen, click the Extensions tab.
  5. Click Add.

Procedure

  1. On the Global Extended Module screen, in the Name field, enter the name of your assembly — for example, CustomExceptionHandler.
  2. In the Assembly field, click the Ellipses button.
  3. Select your custom assembly — for example, CustomExceptionHandler.dll.
  4. Click Open.

    The Class Name field completes.

  5. Click OK.
  6. (Optional) To set additional configuration properties for this AgileConnector, do this procedure.
    1. Click Configure.
    2. On the Custom Form screen, configure the rules.
    3. Click OK.

Implement the Example AgileConnector in AgilePoint NX Portal

To implement the custom Exception Handler AgileConnector, do the procedure in this topic.

Figure: Agile Properties screen

Agile Properties screen

Prerequisites

Good to Know

  • To use the Global Exception Handling option, you do not need to do anything extra in the system activity code, the implementation is specified in the Process Builder.

How to Start

  1. Do one of these:
  2. On the App Explorer screen, do one of these:
  3. On the Process Builder, select a system activity.
  4. Click Properties Properties icon > Agile Properties Agile Properties icon.

Procedure

  1. On the Properties - System Activity screen, do one of these.
    • To save the exception handling information for a system activity in the SaveErrorMessageTo and SaveStatusTo properties, do this procedure.
      1. In the ExceptionHandlerScope property field, select Local.
    • To save the exception handling information for a system activity in the SaveErrorMessageTo and SaveStatusTo properties and include the extended ability to call a custom AgileConnector to handle the exceptions, do this procedure.
      1. In the ExceptionHandlerScope property field, select Global.