Skip to main content
Skip table of contents

Mass data task

Mass data task

Previous issues

Previously, the processing of large data volumes was subject to some limitations and forced the process creator to resolve these issues by creating a special structure for one or more processes.

The solution approach for each of the issues was quite cumbersome:

  1. Search result limit of 10000
    The max. number of search results that can be returned is limited to 10000 in the standard. That is done for good reason, because large amounts of data also need large amounts of resources. In order to work around this issue, the search would be executed again in cycles and limited to specifics in order to filter out data that had already been processed.

    1. One issue can be found in parallel database transactions and interim database changes, which result in the multiple processing of some datasets.

    2. Another issue is the data maintenance in the process. Maintaining the search result total of 10000 as a process variable requires a lot of resources in the CRM system.

  2. Transaction limits are exceeded
    The processing of data, incl. reference fields and relations requires quite some time depending on the data model. Runtime can be additionally extended due to communication with external systems. The default transaction time of 5 min was surpassed if the block size selected was to large for processing. The transaction intermediate event allows the extension of the available transaction time for block processing up to 24h.

    1. One basic problem of the transaction intermediate event is its behavior in case of an error. The process will continue running in an error loop in the system and can only be canceled by the administrator. The process cannot be restarted.

    2. The processes were separated as a workaround for this issue. The external process will now call up the work processes in cycles. The problem that arises here is that this can result in numerous "dead" process instances, which block the CRM system resources.

  3. The runtime and memory consumption increase with the transaction length
    The more data are processes in a transaction, the longer the system will need to process individual datasets. That is why we introduced block processing. The block size is based on experience values and must be modeled new for each new process.

Mass data task

To solve the above issues, the mass data task was introduced in BPM. For BPM, this element is a transaction-interrupting event, replaces the script task for data processing automatically takes over the mass data processing tasks. The process shown prepares the mass data task by creating the search on which it will be based. You can use a search previously stored in the system, create a new search or modify an existing one via the script task or use a user-adjusted search via the BPM search mask. The search must be stores as a process variable of type ISearch.

The mass data task interrupts the process run and inserts a background task on the mass data server. If there is no mass data server stored in the system preferences, then the own server will be used for processing. The processing via the mass data server logic ensures that the action will be continued even if the application server is restarted in the meantime. The current status of the action can be viewed via the Job Queue and Mass Data Task entity in the admin menu. The description contains the process instance ID and the type PROCESS_MASSDATA.

Execution on the mass data server with search

Before the data is processed by the script, a search will be executed without a top count and selects only the primary key from the search result for a temporary table. In the script, the primary key for each individual dataset from the search result is available via the process variable massDataEntryPk. The variable massDataEntryContainer is an empty IContainer with this primary key. The search result can be sorted by a search order created with WorkSpaceScriptUtils.createSearchOrder() . The fields in the search sequence must be defined as search result fields in the search.

During the installation of new saved searches via CURSOR-BPM, "-1" is always entered as default for the top count. The process creator can then manually change this default value if necessary.


The script will then be executed for each dataset in an own transaction, until all data from the temporary table has been processed. If special rights are required for processing, then a specific technical user can be stored for the mass data task.

The intermediate process results are logged in the entity "Mass data task" and can be viewed via the admin menu in the CRM system. It is not possible to create or change process variables in the mass data action, since the action takes place outside the process engine. The process name is noted in the subject. The result total increases with each successfully processed dataset. The current status is recorded in the log text. If there are any script errors during processing, then the transaction for the relevant dataset will be rolled back and an entry is written in the table "Mass data protocol". The mass data protocol can be found in the sub area of the mass data task. The relevant error message for each dataset containing an error can be viewed there. The entire mass data task can be aborted at the first error. All datasets processed to that point will remain intact, including their changes.

When all datasets from the temporary table have been processed via the script, then the system job in the jobs queue ends and automatically continues the process. The processing of the mass data task can later be evaluated in the process. The primary key of the entity "Mass data task" is written to the specified variable. That allows the tracking of specifically those datasets containing errors. The process will not have a log listing all successfully processed datasets, because the data volume can quickly become too large. For such a log, specific criteria in the datasets would have to be evaluated.

Example for post-processing
GROOVY 
IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");

ISearch search = SearchUtils.createSearch("MassDataLog", SearchUtils.createSearchCondition("MassDataTaskKey.MassDataLog", false, false, SearchUtils.EQUAL, LookupUtils.toLookup(massDataTaskPk)));
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("ShortAbstract.MassDataLog", false, true, SearchUtils.NO_CONDITION))
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("EntryPk.MassDataLog", false, true, SearchUtils.NO_CONDITION))
 
List<IContainer> massDataLogs = WorkSpaceScriptUtils.searchForRead(search);
int errorCount = massDataLogs.size();


if(errorCount == 0) {
  ScriptUtils.info("All fine: Execute mass data script for " + resultCount + " contact persons");
} else {
  ScriptUtils.error("Failure: mass data script fails for " + errorCount + " contact persons");
}

Execution on the mass data server with IContainer

There are use cases where mass data processing with non-persistent CRM data is needed because the data comes from external sources. Instead of determining the data by search, the data is read from the external source and prepared for the process as IContainer data and made available to the mass data task for processing. Each IContainer needs a unique primary key for this purpose. If this is empty, a new primary key is generated by the system.

GROOVY 
// Hilfsmethode um die IContainer-Daten für die Massendatenaktion einzulesen
List<List<IContainer>> containers = readContainerData(...);
String massDataTaskPk = MassDataUtils.createMassData(containers);
 
// Hilfsmethode um die zusätzlich IContainer-Daten einzulesen
List<IContainer> additionalContainers = readAdditionalContainerData(...);
MassDataUtils.appendMassData(massDataTaskPk, additionalContainers);
 
// Zuordung zu einer Prozessvariablen vom Typ Primärschlüssel für weitere Verwendung innerhalb der Massendatenaktion
ProcessUtils.setVariable("massDataTaskPk", massDataTaskPk);

In the script action before mass data processing, the IContainer data is passed to the MassDataUtils script class, which creates a mass data task in CRM, creates an associated temporary table in the database, and stores the IContainer data there. It is also possible to read the external data in blocks to keep the memory consumption low at runtime. The processing of the data in the mass data task takes place in the order in which the data was written to the table.

Important

The IContainer data should never be stored in large quantities as process variable, as this can significantly impair the performance and runtime environment of the processes!

In the mass data task, the definition of the search or the search sequence is now omitted. In the mass data task itself, in addition to the possibly generated primary key in the variable massDataEntryPk, the previously cached IContainer is also available as a variable massDataTaskContainer.

GROOVY 
// Verarbeitung in der Massendaten-Aktion
IContainer container = ProcessUtils.getVariable("massDataTaskContainer");

...

Further processing is handled in a separate transaction for each dataset. If an IContainer variable can not be recovered from the database, this is recorded as an error entry for the mass data task in the mass data protocols, as well as if an error should occur in the processing script.

Execution on the mass data server with IContainer list

If further data sets are required for processing per main dataset, additional IContainer variables can be compiled as a list. It is also possible to process different datasets per step, although a constant dataset constellation is more advisable for the maintainability of the process.

GROOVY 
// Hilfsmethode um die IContainer-Listen-Daten für die Massendatenaktion einzulesen
List<List<IContainer>> containers = readContainerData(...);
String massDataTaskPk = MassDataUtils.createMassData(containers);
 
// Hilfsmethode um die zusätzlich IContainer-Listen-Daten einzulesen
List<List<IContainer>> additionalContainers = readAdditionalContainerData(...);
MassDataUtils.appendMassData(massDataTaskPk, additionalContainers);
 
// Zuordung zu einer Prozessvariablen vom Typ Primärschlüssel für weitere Verwendung innerhalb der Massendatenaktion
ProcessUtils.setVariable("massDataTaskPk", massDataTaskPk);

For processing in the mass data actions, the IContainer data is now available as a list in the variable massDataTaskContainerList . The order of the Icontainer data remains stable for each individual step (inner list) and for the entire run (outer list).

GROOVY 
// Verarbeitung in der Massendaten-Aktion
List<IContainer> containers = ProcessUtils.getVariable("massDataTaskContainerList");

...

Serial letter campaign

Serial letters processes via the mass data server can now be created from the process. All settings for the serial letter wizard, e.g. the template name, a search, the subject, etc., can now be prepopulated in the mass data task from process variables.

Once the process has started, the serial letter wizard is displayed to the user as usual via the system jobs in the quick start bar. The user can make further adjustments as needed. The configuration can, however, be designed in such a way that the wizard will not be displayed and the serial letter creation runs completely in the background.

The process will only continue, once processing is completed or canceled.

Configuration

The configuration is checked before a run. If the configuration is invalid, e.g. the selected serial letter template is unavailable, then the serial letter task will not be executed. Instead, all faulty configuration parameters of the serial mail task will be noted in the sub area of the "Mass data protocol" of the entity "Mass data task" and the process will then continue. That means that errors can be found in retrospect and can be corrected for future actions. The following variables are mandatory for the run of a serial letter task.

Mass data task variable name

The variable in which the primary key from the log dataset of the entity "Mass data task" is stored. This dataset will provide read information for the serial letter creation during the course of the process.

Server actions

The extent to which actions can be processed in the wizard, or to which the wizard can be worked in the background, can be controlled via the server action selection:

  • Open wizard
    The wizard is configured according to the specifications and is displayed to the user as usual via the system jobs in the quick start bar.
    Existing entries can be changed by the user and missing entries can be added.

  • Execute search and open wizard
    The wizard is configured according to the specifications and the search is executed directly. The wizard with an existing search result is displayed to the user as usual via the system jobs in the quick start bar. Existing entries can be changed by the user and missing entries can be added.

  • Execute all chosen actions and open wizard
    The wizard is configured according to the specifications and the selected tasks are executed directly.
    The wizard with previously executed tasks is displayed to the user as usual via the system jobs in the quick start bar.
    Any tasks that have not yet been executed (e.g. activity generation or document export) can be executed by the user later on.
    Possible actions include:

    • Execution of the search (always)

    • Document generation (always)

    • Generation of log and reminder activity
      occurs only if the assigned process variable "Protocol activity" or "Reminder activity" has an activity pre-assigned

    • Export of documents
      occurs only if the assigned process variable "Export path" is pre-assigned

  • Execute all actions without opening wizard
    The wizard is configured according to the specifications and the selected tasks are executed directly. The wizard will not be displayed. The process will continue directly after the execution.

Template name

The serial letter template specified the type of serial letter processing

  • Serial letter with separate documents:
    Existing serial letter templates can be used here. The attribute "Single documents available" must be activated!

  • Serial letter for mass data:
    Special "native" templates of type "Mass data" are required here.

Verification criteria

  • The document template must be available and must be activated.

  • The document template type must fulfill the above criteria.

GROOVY 
ProcessUtils.setVariable("docTemplateName", "SERIENBRIEF BLANKO (Beispiel)");

The search can be pre-assigned as an ISearch object. The main search of the search container of the serial letter template is replaced by the forwarding search.
If the relevant process variable is not populated then the search container from the serial letter template is uses

Verification criteria
Possible values of the process variables

  • empty or unpopulated

  • Object of type ISearch
    The entity name and the search field results must match those of the main search and the search container of the serial letter container.

GROOVY 
//Laden der Hauptsuche des Suchbehälters
ISearch search = DocumentUtils.getMainSearch("SERIENBRIEF BLANKO (Beispiel)");
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("TradeKey.Customer", false, true, SearchUtils.EQUAL, LookupUtils.toLookup("S_BRA-CB")));
 
ProcessUtils.setVariable("search", search);

Sorting the amount of data

The sort sequence for the selection result can be specified as ISortOrder object for the serial letter. Sorting is taken into account when exporting the individual documents, so that, for example, sorting by ZIP code is possible in order to optimize shipping.
Sorting in the standard system is always in ascending order, but can also be done in descending order using the optional parameter sortOrderDescending.
The object is created using the method MassDataUtils.createSortOrder(String searchAliasName, String attributeName, boolean sortOrderDescending).
The following methods are available in the return object ISortOrder

  • void addSortField(String searchAliasName, String attributeName)
    Extending the sort order by an additional sort field

  • void addSortField(String searchAliasName, String attributeName, boolean sortOrderDescending)
    Extending the sort order by an additional sort field with specified sort direction (descending / ascending)

Verification criteria
Possible values of the process variables

  • empty or unpopulated

  • Object of type ISortOrder
    This contains the list of sort fields. The following check criteria apply to the sort fields.

    • The search alias name must exist in the search container assigned to the document template.

    • The field name (AttributeName) must exist in the search that belongs to the search alias name. If the field name exists more than once, the first field name found is used as the sort field.

GROOVY 
// Konfiguration einer Sortierung über vier Felder
ISortOrder sortOrder = MassDataUtils.createSortOrder("ADR", "ZIPKey.Address", true);
sortOrder.addSortField("GP", "Name1.Customer");
sortOrder.addSortField("Ansprech", "LastName.ContactPerson");
sortOrder.addSortField("Ansprech", "FirstName.ContactPerson", true);
 
// Zuordung zu einer Prozessvariablen vom Typ Object für weitere Verwendung innerhalb der Massendatenaktion 'Serienbrief'
ProcessUtils.setVariable("sortOrder", sortOrder);

Document subject

Subject of the generated document sets

Verification criteria
This parameter must be filled if the document generation is carried out directly (server task = "Execute all selected actions"). Otherwise, the subject is filled via the wizard, as this field cannot be empty.

GROOVY 
ProcessUtils.setVariable("docSubject", "Änderung AGB");

Output format

A document output format can be selected. The default is given by the template.

Verification criteria
Possible values of the process variables

  • empty or unpopulated
    The output format of the document template is used

  • DocumentUtils.DOC_SAVEFORMAT_DOC

  • DocumentUtils.DOC_SAVEFORMAT_DOCX

  • DocumentUtils.DOC_SAVEFORMAT_PDF

GROOVY 
ProcessUtils.setVariable("saveFormat", DocumentUtils.DOC_SAVEFORMAT_PDF);

Protocol/Reminder activity

The "Protocol/Reminder activity" can be preconfigured. The fields of the wizard page can be prepopulated for activity capture. That includes the fields

  • "Subject" (Subject.Activity)

  • "Text" (Text.Activity)

  • "Starts on" (StartDate.Activity)

  • "Priority" (Priority.Activity)

  • "Reason" (ContactReason.Activity)

  • "Result" (ContactResult.Activity)

  • "Type" (ActTypeKey.Activity)


No activity will be generated if the relevant process variable remains empty.

Verification criteria
Possible values of the process variables

  • empty or unpopulated

  • IContainer of type "Activity"

    • AttributeValue "Priority" (Priority.Activity), "Reason" (ContactReason.Activity), "Result" (ContactResult.Activity), "Type" (ActTypeKey.Activity)

      • empty or not existing
        The stored default value of the field is used

      • LookupVO
        The primary key of the LookupVO is checked for validity

    • AttributeValue "Subject" (Subject.Activity)
      This parameter must be filled if the activities generation is carried out directly (server task = "Execute all selected actions"). Otherwise, the subject is filled via the wizard, as this field cannot be empty.

    • AttributeValue "Starts on" (StartDate.Activity)

      • empty or not existing
        The stored default value is used (current timestamp plus 3 days/custom timespan)

      • Date, Timestamp

    • Other fields from the activity, e.g. FreeText1.Activity
      Notes:

      • Pk and fields from the TableTail (e.g. CreateUser) are ignored.

      • In the case of entity lookup fields, the Pk is simply passed to the entity.

      • In the case of key lookup fields, a LookupVO must be created (e.g. using LookupUtils.toLookup(...)).

GROOVY 
IContainer activityAC = WorkSpaceScriptUtils.createEmptyEntry("Activity", "actPk1");
WorkSpaceScriptUtils.setValue(activityAC, "Subject.Activity", "Änderung AGB");
WorkSpaceScriptUtils.setValue(activityAC, "Text.Activity", "<html><body>Serienbrief für geänderte AGBs</body></html>");
WorkSpaceScriptUtils.setValue(activityAC, "Priority.Activity", LookupUtils.toLookup("S_PRIOR-C"));
WorkSpaceScriptUtils.setValue(activityAC, "ActTypeKey.Activity", LookupUtils.toLookup("S_ACTTYPE-DO"));

WorkSpaceScriptUtils.setValue(activityAC, "FreeText1.Activity", "Sein Lieblingsgericht ist Malzbierbraten");
WorkSpaceScriptUtils.setValue(activityAC, "FreeNumber1.Activity", 123);
WorkSpaceScriptUtils.setValue(activityAC, "FreeDate1.Activity", DateUtils.parseDate("04.05.2020", "dd.MM.yyyy"));
WorkSpaceScriptUtils.setValue(activityAC, "Outbound.Activity", "testpkCaOut");
WorkSpaceScriptUtils.setValue(activityAC, "IsInbound.Activity", true);
WorkSpaceScriptUtils.setValue(activityAC, "OutbChannel.Activity", "P-C0OUTBCHANNEL");
// error case for example
// WorkSpaceScriptUtils.setValue(activityAC, "FirstName.ContactPerson", "Traudel");

ProcessUtils.setVariable("protocolActivity", activityAC);

Employee allocation

The employee assignment for the "Protocol/Reminder activity" can be preconfigured.

Verification criteria
Possible values of the process variables

  • empty or unpopulated
    The default assignment for employees is used. The current employee is assigned to the activity as "Delegated by" with the relationship "Recipient".

  • List of IContainers of type "Employees"

    • All list entries must have the type "IContainer"

    • The entity of the IContainer must be "Employee"

    • The primary key of the IContainer must be populated and valid:

      • An active employee set exists for the relevant primary key OR

      • The specified primary key is an employee variable contained in the template mapping.
        The following employee variables can be used in a template mapping

        • SERIALEmployeeSales

        • SERIALEmployeeKey

        • SERIALEmployeeQuote

        • SERIALEmployeeExtra1

        • SERIALEmployeeExtra2

    • AttributeValue "Relationship type of Employee" (RELATIONTYPEKEYEM.Employee)
      Possible values:

      • empty or unpopulated
        The default relationship "Recipients" is used.

      • LookupVO
        The primary key of the LookupVO is checked for validity

    • AttributeValue "Delegated by" (DelegatedByFlag.Employee)
      The flag must be used only once in the list of employees.

    • AttributeValue "Delegated to" (DelegatedToFlag.Employee)
      The flag must be used only once in the list of employees.

GROOVY 
// Alternative vollständige Variante - Beispiel mit 3 Mitarbeitern
IContainer employeeACDelBy = WorkSpaceScriptUtils.createEmptyEntry("Employee", "employee1");
WorkSpaceScriptUtils.setValue(employeeACDelBy, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-TO"));
WorkSpaceScriptUtils.setValue(employeeACDelBy, "DelegatedByFlag.Employee", true);

IContainer employeeACDelTo = WorkSpaceScriptUtils.createEmptyEntry("Employee", "SERIALEmployeeSales");
WorkSpaceScriptUtils.setValue(employeeACDelTo, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-TO"));
WorkSpaceScriptUtils.setValue(employeeACDelTo, "DelegatedToFlag.Employee", true);

IContainer employeeAC = WorkSpaceScriptUtils.createEmptyEntry("Employee", "employee3");
WorkSpaceScriptUtils.setValue(employeeAC, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-BCC"));

List<IContainer> employeeList = new ArrayList<>(3);
employeeList.add(employeeACDelBy);
employeeList.add(employeeACDelTo);
employeeList.add(employeeAC);
 
ProcessUtils.setVariable("protocolActivityEmployees", employeeList);

Export path

Prepopulation of the path to which the generated serial letter documents are exported. More precisely – the individual documents are copied automatically to a separate sub directory for each user and serial letter action.
A direct execution without wizard is not possible if no sub directory name is provided. The wizard will in this case open automatically.

CODE 
ProcessUtils.setVariable("exportSubDir", "AGB_2017_02");

Execution

A configuration for the serial letter action is created and verified at the start of the mass data task "Serial letter". If the check was successful, then the serial letter action will start. Depending on the server action selected, some actions will be executed beforehand on the mass data server and the result will be displayed to the user as usual via the system jobs in the quick start bar.

Examples for the wizard display depending on the selected server action

  • "Execute search and open wizard"

  • Server action "Execute all selected actions and open wizard" in case of a not preconfigured export path

The user can make further adjustments as needed. Further actions such as document export could be started.
The configuration can, however, be designed in such a way that the wizard will not be displayed and the serial letter creation runs completely in the background.


The process continues, once the wizard is completed or all actions have been processed in the background (without the wizard). Post-processing in the process could look like this.

Example for post-processing
GROOVY 
String massDataTaskPk = ProcessUtils.getVariable("massDataPk");
IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");
String exportDir = WorkSpaceScriptUtils.getValue(massDataTask, "ExportSubDir.MassDataTask");
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");
ProcessUtils.setVariable("resultCount", resultCount);
ProcessUtils.setVariable("exportDir", exportDir);
 
// z.B. Weiterverarbeitung der Prozessvariablen 'resultCount' und 'exportDir' in einer Nachricht oder Mail
 

Error handling

The serial letter action will not be started if the configuration verification was unsuccessful and will be aborted instead. All incorrect configurations are stored in the sub area "Mass data protocol" for the current "Mass data task". This facilitates the correction of the BPM process in retrospect.
The process will not be aborted if this error occurs.

Serial mail action

Serial mails can now also be created just like the serial letters from the process via the mass data server. All settings for the serial mail wizard, e.g. the template name, a search, the subject, etc., can now be prepopulated in the mass data task from process variables.

Once the process has started, the serial mail wizard is displayed to the user as usual via the system jobs in the quick start bar. The user can make further adjustments as needed. The configuration can, however, be designed in such a way that the wizard will not be displayed and the serial mail creation runs completely in the background.

The process will only continue, once processing is completed or canceled.

Configuration

The configuration is checked before a run. If the configuration is invalid, e.g. the selected serial mail template is unavailable, then the serial mail action will not be executed. Instead, all faulty configuration parameters of the serial mail task will be noted in the sub area of the "Mass data protocol" of the entity "Mass data task" and the process will then continue. That means that errors can be found in retrospect and can be corrected for future actions.

Preconditions and verification criteria

A mail configuration containing a server-side groupware connection must be accessible for the current user. This can be saved as

  • a user-specific mail configuration for the web client

  • a system-specific mail configuration (if a user-specific mail configuration for the web client is not feasible)

  • a system-wide mail configuration for serial mails

The configuration is deemed invalid if that is not the case and the serial mail action will not be executed. The following variables are mandatory for the run of a serial mail action.

Mass data task variable name

The variable in which the primary key from the log dataset of the entity "Mass data task" is stored. This dataset will provide read information for the serial mail creation during the course of the process.

Server actions

The extent to which actions can be processed in the wizard, or to which the wizard can be worked in the background, can be controlled via the server action selection:

  • Open wizard
    The wizard is configured according to the specifications and is displayed to the user as usual via the system jobs in the quick start bar.
    Existing entries can be changed by the user and missing entries can be added.

  • Execute search and open wizard
    The wizard is configured according to the specifications and the search is executed directly. The wizard with an existing search result is displayed to the user as usual via the system jobs in the quick start bar. Existing entries can be changed by the user and missing entries can be added.

  • Execute all chosen actions and open wizard
    The wizard is configured according to the specifications and all tasks are executed directly.
    The wizard with previously executed tasks is displayed to the user as usual via the system jobs in the quick start bar.
    The last screen of the wizard with a summary of the mail action is displayed.
    The actions executed include:

    • Execution of the search (always)

    • Sending of the mails (always)

    • Generation of activities with relevant msg file as document (always)

  • Execute all actions without opening wizard
    The wizard is configured according to the specifications and all tasks are executed directly. The wizard will not be displayed. The process will continue directly after the execution.

Template name

Name of the serial mail template used in the serial mail action.

Verification criteria

  • The document template must be available and must be activated.

  • Document template of type "Serial mail"

GROOVY 
ProcessUtils.setVariable("docTemplateName", "SERIENMAIL");

Search

The search can be pre-assigned as an ISearch object. The main search of the search container of the serial mail template is replaced by the forwarding search.
If the relevant process variable is not populated then the search container from the serial mail template is uses

Verification criteria
Possible values of the process variables

  • empty or unpopulated

  • Object of type ISearch
    The entity name and the search field results must match those of the main search and the search container of the serial mail container.

GROOVY 
//Laden der Hauptsuche des Suchbehälters
ISearch search = DocumentUtils.getMainSearch("SERIENMAIL");
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("TradeKey.Customer", false, true, SearchUtils.EQUAL, LookupUtils.toLookup("S_BRA-CB")));
 
ProcessUtils.setVariable("search", search);

Mail subject

Subject of the serial mail to be sent

Verification criteria

This parameter must be filled if the mail generation is carried out directly (server task = "Execute all selected actions"). The subject must be entered by the user via the wizard if that parameter is empty, because this field cannot be empty.

GROOVY 
ProcessUtils.setVariable("mailSubject", "Rückwirkender Preisnachlass");

Mail text

Main body of text of the serial mail to be sent

Verification criteria

  • This parameter must be filled if the mail generation is carried out directly (server task = "Execute all selected actions"). The text body must be entered by the user via the wizard if that parameter is empty, because this field cannot be empty.

  • A stored text body must be formatted in html (starts and ends with a html tag).

GROOVY 
ProcessUtils.setVariable("mailBody", "<html><body>Wir freuen uns, Ihnen mitzuteilen, rückwirkend einen Rabatt in Höhe von 50% zu gewähren.</body></html>");

Mail priority

Priority of the serial mail to be sent.

Verification criteria
Possible values if the process variables (capitalization is disregarded)

  • empty or unpopulated
    The default value "Normal" is used.

  • Low

  • Normal

  • High

GROOVY 
ProcessUtils.setVariable("mailPrio", "High");
ProcessUtils.setVariable("mailPrio", "HIGH");

Generate single activities

Specifies, whether an individual activity should be generated for each mailing or only one activity for the entire mail action.

GROOVY 
ProcessUtils.setVariable("multipleActivities", true);

Internal documents

List of internal documents to be attached to the serial mail.

Verification criteria
Possible values if the process variables (capitalization is disregarded)

  • empty or unpopulated
    No internal documents will be attached to the serial mail.

  • List of primary keys for documents

    • All entries in the list must be of type "String".

    • An active document dataset is available for each entry.

    • The document dataset found is currently not in editing, i.e. not checked out.

GROOVY 
List documentPks = new ArrayList();
documentPks.add("M1be0hpk70MAS2Do");
documentPks.add("M1be0hpk70MAS1Do");
ProcessUtils.setVariable("internalDocuments", documentPks);

External documents

List of external documents to be attached to the serial mail.

Verification criteria
Possible values if the process variables (capitalization is disregarded)

  • empty or unpopulated
    No external documents will be attached to the serial mail.

  • List of completely qualifies file names

    • All entries in the list must be of type String.

    • A file exists for each entry

    • The mass data application server has access to all files in the list

GROOVY 
List documentFiles = new ArrayList();
documentFiles.add("c:\\Temp\\2307.txt ");
documentFiles.add("c:\\Temp\\Eclipse.jpg");
ProcessUtils.setVariable("externalDocuments", documentFiles);

Type of mail configuration

The mail configuration selection can be controlled as follows:

  • User-specific mail configuration (exclusively)
    The mail configuration stored for the employee (field "Groupware web client" ("WebGroupwareKey.Employee")) is used.


    Verification criteria:

    • The mail configuration stored there must not be empty

    • The server-side groupware connection is used in the mail configuration.

  • System-wide mail configuration for serial mails (exclusively)
    The mail configuration defined in the system preferences is used.


    Verification criteria:

    • The mail configuration stored there must not be empty

    • The server-side groupware connection is used in the mail configuration.

  • User-specific mail configuration (preferred)
    The mail configuration stored for the employee has preference. The system-wide mail configuration for serial mails is used if this configuration is empty
    Verification criteria:

    • The mail configuration must not be empty

    • The server-side groupware connection is used in the mail configuration.

  • System-wide mail configuration for serial mails (preferred)
    The mail configuration defined in the system preferences is preferred. The mail configuration stored for the employee (field "Groupware web client" ("WebGroupwareKey.Employee")) will be used if that configuration is empty or is not configured for the server-side groupware connection.
    Verification criteria:

    • The mail configuration must not be empty

    • The server-side groupware connection is used in the mail configuration.

It is not possible to store a fixed mail configuration. At runtime, one of the four available options can be set by variable.

Execution

The execution of the serial mail action is similar to that of the serial letter action. In case some post processing is required, the user can refer back to the size of the selection result quantity. Beyond that, hardly any meaningful information will be available about the serial mail action for further processing.

Excel template action

Template-based Excel files can now also be created from the process, which are processed on the mass data server. In the mass data action, all settings of the Excel Wizard, e.g. the template name, a search, the subject, etc. can be preset from process variables.

Once the process has started, the Excel Wizard is displayed to the user as usual via the system jobs in the quick start bar. The user can make further adjustments as needed. The configuration can, however, be designed in such a way that the wizard will not be displayed and the Excel template creation runs completely in the background.

The process will only continue, once processing is completed or canceled.

Configuration

The configuration is checked before a run. If this is not valid. e.g. the stored Excel template does not exist or the specified source entity does not exist or similar, the action will not be executed. Instead, all faulty configuration parameters of the serial mail task will be noted in the sub area of the "Mass data protocol" of the entity "Mass data task" and the process will then continue. That means that errors can be found in retrospect and can be corrected for future actions.
The following variables are mandatory for the run of a Excel template action.

Mass data task variable name

The variable in which the primary key from the log dataset of the entity "Mass data task" is stored. This dataset will provide read information for the Excel creation during the course of the process.

Server actions

The extent to which actions can be processed in the wizard, or to which the wizard can be worked in the background, can be controlled via the server action selection:

  • Open wizard
    The wizard is configured according to the specifications and is displayed to the user as usual via the system jobs in the quick start bar.
    Existing entries can be changed by the user and missing entries can be added.

  • Execute search and open wizard
    The wizard is configured according to the specifications and the search is executed directly. The wizard with an existing search result is displayed to the user as usual via the system jobs in the quick start bar. Existing entries can be changed by the user and missing entries can be added.

  • Execute all chosen actions and open wizard
    The wizard is configured according to the specifications and the actions Search and Generate Excel document are executed directly.
    The wizard with previously executed tasks is displayed to the user as usual via the system jobs in the quick start bar.
    The following situation can be found when opening the wizard:

    • Executed search

    • Generated Excel file

    • Opening Excel file
      The wizard page for opening the Excel file is displayed

    • The following is the page (if the "as document dataset is enabled" option)

      • Display of the page for the new creation of the document dataset

      • Display the page for linking the document dataset

      • Back transfer of the data
        If a retransfer is configured in the Excel template, the user is always prompted to open the Excel file in order to be able to make changes before the retransfer.
        Then the actions "Create document dataset" and "Transfer data from Excel to CRM" can be called in the wizard.

    • Display of the "Result" wizard page

  • Execute all actions without opening wizard
    The wizard is configured according to the specifications and the selected tasks are executed directly. The process will continue directly after the execution.
    Ideally, there is no display of the wizard unless opening the Excel file is required. The wizard page for opening the Excel file is displayed under the following conditions:

    • The generated Excel file contains a macro.
      Background: The macro can be executed only on the client.

    • In the Excel template the retransfer of the data is configured.
      Background: The user can thus still make changes to the Excel file before transferring it back to CRM.

Template name

The Excel template is required and determines the type of processing

Verification criteria

  • The Excel document template must exist and be active

  • is based on the "NATIVE" generation variant

GROOVY 
ProcessUtils.setVariable("docTemplateName", "Name der Excelvorlage");

Search

The search can be pre-assigned as an ISearch object. The main search of the search container of the serial letter template is replaced by the forwarding search.
If the relevant process variable is not populated then the search container from the serial letter template is uses

Verification criteria
Possible values of the process variables

  • empty or unpopulated

  • Object of type ISearch
    The entity name and the search field results must match those of the main search and the search container of the serial letter container.

GROOVY 
//Laden der Hauptsuche des Suchbehälters
ISearch search = DocumentUtils.getMainSearch("Name der Excelvorlage");
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("TradeKey.Customer", false, true, SearchUtils.EQUAL, LookupUtils.toLookup("S_BRA-CB")));
 
ProcessUtils.setVariable("search", search);

Sorting the amount of data

The sort sequence for the selection result can be specified as ISortOrder object for the serial letter. The sorting is taken into account in the output to the Excel file.
Sorting in the standard system is always in ascending order, but can also be done in descending order using the optional parameter sortOrderDescending.
The object is created using the method MassDataUtils.createSortOrder(String searchAliasName, String attributeName, boolean sortOrderDescending).
The following methods are available in the return object ISortOrder

  • void addSortField(String searchAliasName, String attributeName)
    Extending the sort order by an additional sort field

  • void addSortField(String searchAliasName, String attributeName, boolean sortOrderDescending)
    Extending the sort order by an additional sort field with specified sort direction (descending / ascending)

Verification criteria
Possible values of the process variables

  • empty or unpopulated

  • Object of type ISortOrder
    This contains the list of sort fields. The following check criteria apply to the sort fields.

    • The search alias name must exist in the search container assigned to the document template.

    • The field name (AttributeName) must exist in the search that belongs to the search alias name. If the field name exists more than once, the first field name found is used as the sort field.

GROOVY 
// Konfiguration einer Sortierung über vier Felder
ISortOrder sortOrder = MassDataUtils.createSortOrder("ADR", "ZIPKey.Address", true);
sortOrder.addSortField("GP", "Name1.Customer");
sortOrder.addSortField("Ansprech", "LastName.ContactPerson");
sortOrder.addSortField("Ansprech", "FirstName.ContactPerson", true);
 
// Zuordung zu einer Prozessvariablen vom Typ Object für weitere Verwendung innerhalb der Massendatenaktion 'Serienbrief'
ProcessUtils.setVariable("sortOrder", sortOrder);

Creating a document

Save the generated Excel file as a document dataset in CRM

Verification criteria

Possible values of the process variables

  • no or not assigned - no document dataset is created

  • yes – a document dataset will be created
    The following document variables must be filled:

    • Source entity

    • Primary key Output entity

    • Document subject (If "Perform all actions without wizard" is selected as server action. Otherwise, the user can always maintain the value via the wizard)

GROOVY 
ProcessUtils.setVariable("createDocument", true);

Source entity

The document dataset must be linked to another record (parent dataset). The entity of the parent dataset is specified

Verification criteria
If document creation or retransfer is configured, this parameter must be filled.

Possible values of the process variables

  • empty, not assigned - only valid if no document dataset is created

  • Name of an existing entity that has an n:m relation to documents

GROOVY 
ProcessUtils.setVariable("parentEntity", "Activity");

Primary key Output entity

The document dataset must be linked to another record (parent dataset). The primary key of the parent dataset is given.

Verification criteria
If document creation or retransfer is configured, this parameter must be filled.

Possible values of the process variables

  • empty, not assigned - only valid if no document dataset is created

  • Primary key of an existing dataset from the entity above

GROOVY 
ProcessUtils.setVariable("parentPk", "othknp1e195610mAc");

Document subject

Subject of the generated document dataset

Verification criteria
If document creation is configured, this parameter must be filled.

Possible values of the process variables

  • empty, not used - only valid if:

    • no document dataset is created

    • or as a server action with wizard is selected. In such a case, the user can maintain the value via the wizard

  • any text

GROOVY 
ProcessUtils.setVariable("docSubject", "Kalkulation");

Keyword

Keyword of the created document dataset (optional parameter)

Verification criteria
Possible values of the process variables

  • empty, not used

  • any text

GROOVY 
ProcessUtils.setVariable("headword", "meine Stichworte");

Category

Category of the created document dataset (optional parameter)

Verification criteria
Possible values of the process variables

  • empty, not used

  • valid primary key of a document category

GROOVY 
ProcessUtils.setVariable("category", "EB-DOCCAT");

Linking with all business partners

The created document dataset should be linked to all business partners of the parent dataset.

Verification criteria
Possible values of the process variables

  • false or not used
    The created document dataset will not be linked to any business partner of the parent dataset.

  • true
    The created document dataset is linked to all business partners of the parent dataset.

GROOVY 
ProcessUtils.setVariable("linkCu", true);

Link to all contact persons

The created document dataset should be linked to all contact persons of the parent dataset.

Verification criteria
Possible values of the process variables

  • false or not used
    The created document dataset will not be linked to any contact person of the parent dataset.

  • true
    The created document dataset is linked to all contact persons of the parent dataset.

GROOVY 
ProcessUtils.setVariable("linkCoPe", true);

Execution

When the mass data action "Excel template" is started, a configuration for the action is first created and checked. If the check was successful, the generation action is started. Depending on the server action selected, some actions will be executed beforehand on the mass data server and the result will be displayed to the user as usual via the system jobs in the quick start bar.

Examples for the wizard display depending on the selected server action

  • "Execute search and open wizard"



  • Server action "Execute all selected actions and open wizard".



  • Server action "Execute all selected actions without wizard" for generated Excel file with macro or back transfer


However, the configuration can also be designed in such a way that no display of the wizard takes place and the Excel generation runs completely in the background, provided that no macros are executed in the generated Excel file and no retransfer is configured.

The process continues, once the wizard is completed or all actions have been processed in the background (without the wizard).
If the generated Excel document was saved as a document record in CRM, the document primary key is available in the "ExportSubDir.MassDataTask" field. Post-processing in the process could look like this.

Example for post-processing
GROOVY 
String massDataTaskPk = ProcessUtils.getVariable("massDataPk");
IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");  
String docPk = WorkSpaceScriptUtils.getValue(massDataTask, "ExportSubDir.MassDataTask");
ProcessUtils.setVariable("resultCount", resultCount);  
ProcessUtils.setVariable("docPk", docpk);
 
// z.B. Weiterverarbeitung der Prozessvariablen 'docPk' und 'resultCount' in einer Nachricht o.ä.

Error handling

If the configuration check was not successful, the generation action is not started but terminated immediately. All incorrect configurations are stored in the sub area "Mass data protocol" for the current "Mass data task". This facilitates the correction of the BPM process in retrospect.
The process will not be aborted if this error occurs.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close