Create a new Workflow Instance

  • 196 Views
  • Last Post 25 May 2016
dwebb posted this 25 May 2016

You can create new Workflow Instances from MVC or WPF apps, or from a BP service host. Start by adding to your project a reference to the Workflow Client Integration assembly, which is in the A4DN Maintenance path:

<Reference Include="A4DN.WF.BOS.ClientIntegration">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(A4DNMaintenanceHintPath)A4DN.WF.BOS.ClientIntegration.dll</HintPath>
</Reference>

This assembly provides two attributes, an interface, and a utility method that will be used to create a new Workflow Instance.

  • [WF_WorkflowInstance("MyWorkflow")] is added to a class that contains properties which correspond to the workflow's custom fields. "MyWorkflow" is the namespace of the Workflow.
  • [WF_WorkflowField] is added to each property. The property name should match the custom field name, but if it doesn't the field name can be specified in the attribute.
  • WF_IWorkflowInstanceData is an interface that the class must implement. There are no properties or methods to add; this is used as a hook for extension methods.
  • this.am_AddToWorkQueue() is an extension method that you call to create the new Workflow Instance.

Here's a simple example of a utility class that's only used for workflow:

[WF_WorkflowInstance("TrialConfirmation")]
public class DemoConfirmation : WF_IWorkflowInstanceData
{
    [WF_WorkflowField]
    public string Token { get; set; }

    [WF_WorkflowField]
    public string Email { get; set; }

    [WF_WorkflowField]
    public string IPAddress { get; set; }

    [WF_WorkflowField]
    public string UserAgent { get; set; }

    [WF_WorkflowField]
    public string Referer { get; set; }
}

Another class can use this to create a new instance for the TrialConfirmation workflow:

new DemoConfirmation
{
    Token = token,
    Email = email,
    IPAddress = HttpContext.Current.Request.UserHostAddress,
    UserAgent = HttpContext.Current.Request.UserAgent,
    Referer = HttpContext.Current.Request.UrlReferrer == null ? "" : HttpContext.Current.Request.UrlReferrer.OriginalString
}.am_AddToWorkQueue(instanceName: "Trial Registration Confirmation for " + email);

The DemoConfirmation object is being created, its am_AddToWorkQueue() method is called, and then the object is destroyed. When used this way, there's no need to hold onto the object that's being passed to Workflow. The instanceName argument is used to set the text that will be displayed in the Workflow Instance search results grid; it can be set per-instance, or it can be set as a default in the [WF_WorkflowInstance] attribute.

Another typical approach is to add the workflow attributes and interface to an existing data model class, such as a data entity. That will give the model an am_AddToWorkQueue() method which can be called to add itself to a workflow. The attributes are designed so that they can be added to any class without interfering with the class or forcing any particular naming convention on the properties.

dwebb posted this 25 May 2016

[WF_WorkflowField] can be applied to any value types, but it can also be applied to object types. If the object's type implements WF_IWorkflowInstanceData, it will automatically be recursed into to capture all of its workflow properties as custom fields. The field names will generally be prefixed with the property name in the top-level class. With an optional argument to specify the fields by name, any object type can also be used:

[WF_WorkflowField("Contact", ap_FlattenChildObjectFields = true, ap_ChildObjectFieldNames = "FirstName,LastName,CompanyName,PhoneNumber,Email,Website,AddressLine1,AddressLine2,City,State,ZipCode,Country,PreferredDatabase,AdditionalComments,IPAddress,UserAgent,Referer,Token")]
public ContactsService.ContactsEntity Entity { get; set; }

ap_ChildObjectFieldNames is a comma-separated list of property names in the object which need to be mapped to custom fields. This lets you pull in fields when you can't add [WF_WorkflowField] attributes to the object.

ap_FlattenChildObjectFields prevents prefixing the fields with "Entity." In the workflow instance, the named properties from ContactsEntity will be stored as if they were properties on the parent class.

Close