Skip to content

User Manual

Jump to bottom
Konstantin edited this page Nov 23, 2017 · 3 revisions

Installation of the ServiceBroker

In order to install the ServiceBroker and all other artifacts, you need to run the Install.ps1 file in the Release package, which will do the following:

  • copy the ServiceBroker binaries (K2Field.ServiceBroker.EmailTemplate.dll) to the ..\K2 Blackpearl\ServiceBroker\ folder;
  • register the Service Type with the name 'K2Field_ServiceBroker_EmailTemplate';
  • deploys the Test package, which contains the following artifacts:
    • ServiceInstance;
    • SmartObjects, some of which already contain data for testing;
    • Examples of Views and Forms, which can be used to configure EmailTemplates and Placeholders;
    • Workflow, which sends Email to the Originator with a predefined template.

Service Authentication

Since the main idea of the Service Broker is to run the ADO.NET queries dynamically, the following Authentication Modes may be used with the Service Type:

  • Impersonate;
  • ServiceAccount; But you need to take into account, that all the SmartObjects, which will be subsequently called from dynamic ADO.NET queries, will use the authentication of their Service Instances. Moreover, the Smartobject, generated from this service instance will be called within the workflow, i.e. by the K2 Service Account.

Configuration of the Service Instance

After you ran the installer, you will have a pre-configured Service Instance, installed on your K2 Server. But you can configure the Service Instance manually. Below you can see the description of the Service Instance Configuration parameters:

  • SMO System Name - this is the system name of the SmartObject, which will contain your dynamic placeholders and the associated ADO.NET queries. In the test package this System SMO is called K2Field_EmailTemplate_SMO_Placeholders. For a detailed explanation of the Schema for such SMO, please, see the section below;
  • SMO List Method Name - this a system name of the List Method to extract all the Dynamic placeholders from the SMO, mentioned above (e.g. GetList);
  • SMO Placeholder Property Name - name of the property from the above-mentioned SMO, where the placeholder names are stored (e.g. Placeholder);
  • AdoNetPropertyName - name of the property from the above-mentioned SMO, where ADO.NET queries are stored (e.g. AdoNetQuery);
  • SMO Return Property - name of the property from the above-mentioned SMO, which contains the name of the property to be returned from ADO.NET query to replace the placeholder in the Email Template (e.g. ReturnProperty)
  • Placeholder Wrapper Symbol - the symbol(s), which will be used by the ServiceBroker to search and replace the placeholders in the ADO.NET queries and Email Templates (e.g. $. Email Subject: Dear $DestinationDisplayName$...);
  • ADO.NET query placeholders, delimited with (;) - a delimited string of placeholders, which can be used in the ADO.NET queries as input parameters (e.g. pDestination;pProcInstId - SELECT [DisplayName] FROM URMService_User WHERE [FQN] = $pDestination$)
  • Static Placeholders, delimited with (;) - the names of the placeholders, which will not be associated with any ADO.NET queries, but will use the data, supplied from the Workflow. This can be such information as Worklist Item URL or Worklfow Datafields (e.g. WorkflowName;ActivityName;MainPageUrl)

Static Parameters Explained

When you need to send the values from the workflow into the Email Template processing SmartObject to replace the placeholders, you can use the Static Placeholders, delimited with (;). When the Service Instance is configured, the delimited string of Static placeholders will be converted into input parameters of the GetEmailTemplate method. The examples of such values, which cannot be obtained from Ado.Net queries, are Worklist Item Link, some Environment Variables or DataFields.

Dynamic Placeholders

If you want to use dynamic placeholders in the workflow, you need to have a separate SmartObject, which can store the placeholders and the associated Ado.Net queries. Then from the workflow you can send certain input parameters, which will help the Ado.Net queries to return the data you need. Below you can find the description of the Placeholders SmartObject schema as well as the explanation how dynamic input parameters work.

Schema of the Placeholders SmartObject

The SmartObject with Dynamic placeholders should contain at least 1 List method and the following properties:

  • Placeholder Property (Text) - Stores the names of the placeholders, which are used in the Email Template (e.g. This is the Request #$RequestId$ of the customer $CustomerName$).
  • AdoNetQuery (Memo) - Contains the Ado.Net queries, associated with the dynamic placeholders. The Service Broker will analyze the Email Template and for every placeholder, which is dynamic, the associated Ado.Net query will be called to get the real value.
  • ReturnProperty (Text) - it contains the name of the property, which needs to be returned from Ado.Net query. The Ado.Net may return one item or a list of items with lots of properties. The ReturnProperty will specify, which value from the result of the Ado.Net query needs to be returned.

Dynamic input parameters

In most of the cases the workflow is associated with one or several items, that are being processed by it, i.e. a request, project, contract, document etc. To keep the reference, the workflow contains the Id of the specific item. When the workflow sends notifications, the users often want the email subjects and bodies to contain various attributes or other data, which are associated with the processed item (e.g. the project name, the request status, the approval type etc.). In order to be able to obtain these items and use them as placeholders in the workflow, you can create the following objects in the Placeholders SmartObject:

  • Placeholder: ProjectName
  • AdoNetQuery: SELECT [Name] FROM ProjectSmo WHERE Id=$pProjectId$
  • ReturnProperty: Name

The queries can be more complex:

  • Placeholder: RequestStatus
  • AdoNetQuery: SELECT [Name] AS [RequestStatus] FROM StatusSmo LEFT JOIN RequestSmo ON RequestSmo.StatusId = StatusSmo.Id WHERE RequestSmo.Id = $pRequestId$
  • ReturnProperty: RequestStatus

The full list of supported Ado.Net queries can be found by this url ADO Query Syntax. If you look closely to the above-mentioned Ado.Net queries, you can notice, that all they use the so-called variables, or dynamic input IDs, i.e. $pProjectId$ and $pRequestId$. These input IDs should be specified in the ADO.NET query placeholders, delimited with (;) service configuration parameter as pProjectId;pRequestId. The ServiceBroker will split the string and turn it into the GetEmailTemplate input parameters. In the workflow you can map these input Ids to the DataFields or other Smo values, so that they are replaced with real values in the runtime and the Ado.Net queries are fulfilled for certain items.

Limitations

There are several limitations in the ServiceBroker, which are listed below:

  • it is not always possible to query Reporting SMOs. Due to asynchronous nature of the K2 reporting, the queried data might not be yet available when the call is made;
Clone this wiki locally