Activity effects

With the WorkZone template, you get a number of WorkZone-specific activity effects.

Note: If you want to expand the data model, for example create a custom type and use it in a case activity, you must expand the data model before you create a case activity in WorkZone Configurator. If you create the case activity first, and then expand the model, the case activity cannot identify the custom type and its associated properties. Users will get an error when they execute the case activity.

This applies to all activity effects that communicate with OData.

See Create a custom type and Create a case activity in the WorkZone Configurator guide.

Check

Check is the basic activity effect, which you can use for creating items on a checklist. You can, for example, use it to provide information that must be read before moving on to the next activity. You can add instructions and links to more information in this activity. This is the default activity effect.

Check parameters

No parameters

CompleteGraph

CompleteGraph completes the process. You can use this activity to allow users to complete a case activity list even if some activities have not been executed, for example, if the activities were not needed in a work process.

CompleteGraph parameters

No parameters

CopyDocuments

CopyDocuments copies documents that are retrieved by a query to the current case. The documents are copied without the source meta data. The access code is verified on the basis of the case handler's or the case owner's access rights. For example, you can use this activity effect to copy standard documents, such as templates to a case.

Return value

The return value of the CopyDocuments effect is the document ID of the copy. If more that one document is copied, only the first document ID is returned. See Reference values from DCR activities for information on how you can reference return values in other activities.

Note: The CopyDocuments activity effect can copy a maximum of 50 documents to a case at the same time.

CopyDocuments parameters

Parameter Description Required

DocumentSource

OData query that identifies the documents to copy.

The example shows how to copy templates with the document type SKAB to the current case.

Example:

/Records?$filter=RecordType_Value eq 'SKAB'&$select=ID,UserKey,Summary

 Yes

DefaultDocumentName

If you copy only one document, you can specify a default name that will be applied to the copied document.

If you copy more than one document, the original name will be used.

 Yes

DocumentType

The document type that will be applied to the copied documents. Yes

DocumentState

The document state that will be applied to the copied documents. Yes

MaxDocumentsToCopy

Defines the maximum number of documents to copy. The default value is 1.

If the maximum number of documents to copy is exceeded, no documents will be copied.

 Yes

EditDocuments

EditDocuments provides a list of documents for editing. The documents on the list are retrieved by a query, for example, documents on a specific case, documents with me as the case handler, and so on.

EditDocuments parameters

Parameter Description Required

DocumentQuery

OData query that searches for the documents to edit. By default all documents are listed. The example shows how to retrieve documents on the current case.

Example: /Records?$filter=FileKey_Value eq '{Case.ID}'

Where Case.ID refers to the current case.

 Yes

MergeDocument

MergeDocument merges the merge fields in a document with values from WorkZone. MergeDocument merges one document at a time. The document will be merged and updated.

Important: The MergeDocument activity effect does not support remerge of a document, which means that a document can only be merged once. See Known issues.

MergeDocument parameters

Parameter Description Required

DocumentQuery

OData query that searches for the document to be merged. The example shows how to retrieve a document that will be merged.

Example: /Records?$filter=ID eq '1234'

Where 1234 refers to the specific document ID of a document that will be merged.

 Yes

StartProcess

StartProcess starts a process or another case activity list. When a user executes the activity, the Start process dialog opens with the specified process.

Return value

The return value of the StartProcess effect is the process instance ID. See Reference values from DCR activities for information on how you can reference return values in other activities.

Automatic execution

You can execute the StartProcess activity effect automatically but it will only work if the process you start does not have any parameters. If you specify a process with parameters, an error message will be written to the activity history when the activity tries to start the process automatically. Note that all standard processes have parameters. Automatic execution works when starting a case activity list or a customized process without parameters. See Execute activities automatically for information about using the AUTO and L-AUTO roles.

StartProcess parameters

Parameter Description Required

ProcessGUID

The GUID of the process you want the activity effect to start.

Tip: You can look up the GUIDs in WorkZone Configurator, see FAQs about case activities.
No

ProcessOwner

Specify the process owner using the NameCode of the process owner or using the case handler on the current case using the notation Case.Officer_Value.

If you add the AUTO or L-AUTO roles, it is required to specify this parameter. Automatic start of the process will fail if the ProcessOwner parameter is not specified.

No

ProcessName

The name of the process that you want the activity effect to start. Add the process name instead of the process GUID to identify the process that you want to start. Use this parameter if you plan to use the case activity across environments, such as your test and your production environment. You cannot use the process GUID to identify the process because the GUID is unique in each environments.

Note: If you have uploaded a custom process package to WorkZone that contains a process with the same name as an existing process, the ProcessName parameter will not work because it cannot identify which of the processes with identical names to start.
See also: Process package development.
Tip: You can look up the process name in WorkZone Configurator, see FAQs about case activities.

No

SendSmartPost

SendSmartPost starts a SmartPost process. In this release, you can send a letter to recipients. By default the SendSmartPost activity is executed automatically.

Return value

The return value of the SendSmartPost effect is the process instance ID. See Reference values from DCR activities for information on how you can reference return values in other activities.

SendProcess parameters

Parameter Description Required

Letter

OData query that specifies which document to send as the letter in the SmartPost message.

Example: /Records?$filter=FileKey_Value eq '{Case.ID}' and (Title eq 'Standard letter')

The query retrieves a document with the title Standard letter from the current case.

Yes

Attachments

OData query that specifies which attachments to include in the message.

Example: /Records?$filter=FileKey_Value eq '{Case.ID}' and (Title eq 'Attachment 1' or title eq 'Attachment 2')

The query retrieves two documents with the titles Attachment 1 and Attachment 2 from the current case.

No

Recipients

Specify the recipients of the message.

You can use an OData query or you can enter the party roles separated by comma. If a party with a specific role is not found on the case or the role is invalid, you can specify which role to use instead after a slash /. You specify as many alternative roles as you need separated by slashes.

OData query

Example: /Addresses?$filter=Name/Files/any(a: a/FileKey_Value eq '{Case.ID}' and a/CustomLabel_Value eq 'Reply-To')

The query retrieves addresses of parties with the role Reply to on the current case.

Simple notation

Example: Reply-To, Høringspart/Sagspart

The query retrieves addresses of parties with the roles Reply to and Hearing party.

If no parties with the role Hearing part (Høringspart) are found parties with the role Sagspart will be retrieved instead.

You must specify the codes for the roles and not the localized labels. You can see the codes in WorkZone Configurator. Go to Case > Parties and references.

Yes

CopyRecipients

Specify the copy recipients of the message.

You can use an OData query or you can enter the party roles separated by comma and alternative roles separated by slashes in the same way as for Recipients.

If the total number of recipients and copy recipients exceeds the maximum allowed number of 50 recipients, the message will not be sent.

No

ProcessGuid

Specify the GUID of the SmartPost process you want the activity to start. Use this parameter if your organization has several SmartPost processes and you want to use to a specific SmartPost process.

If you do not specify a GUID, the GUID of the default SmartPost process is used.

Tip: You can look up the GUIDs in WorkZone Configurator, see FAQs about case activities.

No

ProcessOwner

Specify the process owner of the SmartPost process. Possible values are:

  • NameCode—Enter the NameCode of the employee who will be the process owner using upper case letters.
  • {Case.Officer_Value}—The case handler on the case where the case activity is started becomes the process owner.
  • {DocumentCaseHandler}—The case handler on letter document that will be sent by SmartPost becomes the process owner.

If the values are invalid, an error message will be written to the history.

Yes

ValidatePDFUA

Specify if you want to use the ValidatePDFUA setting in the SmartPost process parameters in WorkZone Configurator. If you set this parameter to Yes, letters and attachments are validated for PDF/UA compliance.

No

ProcessName

The name of an active SmartPost process that you want the activity effect to start. Add the process name instead of the process GUID to identify the process that you want to start. Use this parameter if you plan to use the case activity across environments, such as your test and your production environment. You cannot use the process GUID to identify the process across environments because the GUID is unique in each environment.

Note: If you have uploaded a custom process package to WorkZone that contains a process with the same name as an existing process, the ProcessName parameter will not work because it cannot identify which of the processes with identical names to start.
See also: Process package development.
Tip: You can look up the process name in WorkZone Configurator, see FAQs about case activities.

No

UpdateEntities

UpdateEntities updates values of specific text fields on a case, for example if you want the case title and the case state of the current case to change after an action has been completed.

The activity effect can be used to update both standard and custom fields.

The following types of fields cannot be updated:

  • Computed and read-only properties. See the WorkZone QueryBuilder documentation for information about which properties of the Files entity are computed.
  • Other entities, for example Case text and Information, if they are empty.
  • Custom droplists.

Current user and organizational unit

You can update fields on a case using @me and @unit to insert the current user as case handler on a case and the current user's organizational unit as the responsible unit.

To add the current user as case handler on the case and the current user's organizational unit as the responsible unit, define the parameters as follows:

Note: When using @Me or @Unit, do not set the UpdateEntities activity effect to execute automatically. It is a system user who executes activities with the AUTO role assigned, and therefore @Me and @Unit will fail. See Execute activities automatically.

UpdateEntities parameters

Parameter Description Required

Entity

Specify which entity you want to get values from, for example Files (Cases).

Yes

Filter

Enter the file key of the case whose values you want to update. If you always want to update the current case, meaning the case on which the case activity is started, you can enter:

ID eq '{Case.ID}'

Tip: You can use WorkZone QueryBuilder to build your query and copy the filter part to this parameter. See How do you copy a query from WorkZone QueryBuilder.

Yes

Property

Specify the properties and values you want to update in JSON format. For example, if you want to update the case state and the case title, enter:

{"State_Value":"UB","Title":"Updated"}

Which will update the State field with the state UB, Being processed and the Title to Updated.

If, for example, you want to update the Title field with the date and time that the current case was updated and the current state, enter:

{"Title":"Title: {Case.Title}, updated: {Case.UpdateTime}, State: {Case.State_Value}"}

Which will update the case title to, for example: Title: Case title, updated: 25-03-2020 11.50.00, State: UB, Being processed.

Tip: You can use WorkZone QueryBuilder to build your query, convert it to JSON format, and copy it to this parameter. See How do you copy a query from WorkZone QueryBuilder.

Yes

ValidateEntities

ValidateEntities allows you to validate values on a case based on a condition that you define, and if the condition is met, the subsequent activities will be included or excluded. The ValidateEntities activity effect works in connection with guards that you define on the Include and Exclude relation types.

Guards

On the Include and Exclude relation types, you need to define guards that validate against the condition you have defined in an activity that holds the activity effect ValidateEntities.

On the Include relation type, enter:

<Activity ID>=1

On the Exclude relation type, enter:

<Activity ID>!=1

This also works vice versa, depending on what you want the process to do.

<Activity ID> is the ID of the activity that holds the ValidateEntities activity effect.

=1 means that the condition you have defined in the activity is met (it is TRUE).

!=1 means that the condition you have defined in the activity is not met (it is FALSE).

ValidateEntities parameters

Parameter Description Required

Entity

Specify which entity you want to get values from, for example Files (Cases).

Yes

Filter

Enter the file key of the case whose values you want to update. If you always want to update the current case, that is the case on which the case activity is started, you can enter:

ID eq '{Case.ID}'

Tip: You can use WorkZone QueryBuilder to build your query and copy the filter part to this parameter. See How do you copy a query from WorkZone QueryBuilder.

Yes

Property

Specify the properties and values you want to validate in JSON format. For example, if you want to validate the value of the case state and the responsible unit, enter:

{"State_Value":"FB","ResponsibleOu_Value":"AS"}

In connection with guards, it will validate if the state is FB and if the responsible unit is AS and then include or exclude the following activities depending on the outcome.

Another example may be to validate the current case state in the title:

{"Title":"Case with state: {Case.State_Value}"}

In connection with guards, it will validate if the title is Case with state: <currentState> and then include or exclude the following activities depending on the outcome.

Tip: You can use WorkZone QueryBuilder to build your query, convert it to JSON format, and copy it to this parameter. See How do you copy a query from WorkZone QueryBuilder.

Yes

ValidationInterval

Specify at which interval you want the ValidateEntity activity to be executed automatically. Use this parameter if you await specific information to be available on a case before the next activity can be executed. For example, a receipt for payment must be saved on the case before the case handling can continue.

Enter the interval in number of minutes. The minimum interval is 30 minutes.

The automatic execution will end when the ValidateEntity activity is no longer active, for example, if is not executable or not included in the process, or when the entire process is completed.

If you have several ValidateEntity activities in a process, the activity with the lowest interval will determine when the entire process will be updated. The process will also be updated if only one of the ValidateEntity activities has this parameter filled in.

If you do not specify this parameter, the user will need to click the Update button in WorkZone Client to update the activity list manually.

No

QueryOptions

Specify OData query options, such as $top, $orderby, $aggregate, and so on. For example, if you have a list of cases and you want to fetch the second to last case, enter:

$OrderByDesc=ID$skip=1, which will sort the cases in descending order and skip the first case in the list.

See Use query options.

No
Example: The example below illustrates the use of the ValidateEntities activity effect together with guards. The title and the state of the current case will be changed and a document will be copied to the case if the case has the state FB and the responsible unit is AS.

The DCR process looks like this:

The Validate case values activity is a ValidateEntities activity effect that validates if the current case has the state FB and the responsible unit is AS. The parameters are defined as follows:

The Include and Exclude relation types have guards that check if the condition above is met.

  • Include relation type:

    • ValidateEntities_Case=1

  • Exclude relation type:

    • ValidateEntities_Case!=1

If the condition is met, the Validate case values activity will hold the value 1, and the Update case title and state activity and the Copy document with title "TestDoc1" activity will be included. If the condition is not met, it will result in !=1 and nothing will happen.

The Update case title and state activity is an UpdateEntities activity effect that changes the case title to Condition met and the state changed to ARK. The parameters are defined as follows:

The Copy document with title "TestDoc1" activity is a CopyDocument activity effect that copies a document named TestDoc1 to the case and name the document Copied document. The parameters are defined as follows:

Example: The example below illustrates the use of the ValidateEntities activity effect together with complex rules that are combined in a guard. The title will be changed to "Condition met - Fully processed" and the state of the current case will be changed to FB, Fully processed automatically if the case has the state UB or the case has the state AB.

The DCR process looks like this:

The Validation activity is a nested activity that holds two activities of the type ValidateEntities. Each nested activity contains a condition.

The first activity Case state is "UB" validates if the current case has the state UB. The parameters are defined as follows:

The second activity Case state is "AB" validates if the current case has the state AB. The parameters are defined as follows:

The Include and Exclude relation types have guards that validate if the above condition is met.

  • Include relation type:

    • ValidateCaseUB=1 or ValidateCaseAB=1

  • Exclude relation type:

    • ValidateCaseUB!=1 and ValidateCaseAB!=1

The condition is met if either the ValidateCaseUB activity or the ValidateCaseAB activity hold the value 1, the Update state and title activity and the Copy document to case activity will be included. If none of the conditions are met, it will result in !=1, and nothing will happen.

The Update state and title activity is an UpdateEntities activity effect that changes the case title to Condition met - Fully processed and the state of the current case to FB, Fully processed. The parameters are defined as follows:

The Copy document to case activity is a CopyDocument activity effect that copies a specific document to the case and names the document Standard letter. The parameters are defined as follows:

Note: Do not use @Me or @Unit in the ValidateEntities activity. The ValidateEntities activity is always executed automatically by a system user, and therefore @Me and @Unit will fail. See Execute activities automatically.

CreateEntity

CreateEntity creates an entity, for example case, a document, a contact, or a custom type.

Return value

The return value of the CreateEntity effect is the ID of the created entity. See Reference values from DCR activities for information on how you can reference return values in other activities.

CreateEntity parameters

Parameter Description Required

Entity

Specify which type of entity to create, for example Files, Records, or FileContacts.

 

Yes

Property

Specify the properties and values you want to create in JSON format. For example, if you want to create a case with a specific case group, a case title, and with the case handler from the case that the case activity is started from, enter:

{"FileClass_Value":"00","Title":"New case", "Officer_Value":"{Case.Officer_Value}"}

Which will create a case with the case group 00, the title New case and the case handler of the current case.

Yes

GetValue

GetValue allows you to fetch a value from an entity, for example a case. You can then use this value in guards to make conditions based on WorkZone data. If the condition is met, the subsequent activities will be included or excluded.

Return value

The return value of the GetValue effect is the property. See Reference values from DCR activities for information on how you can reference return values in other activities.

GetValue parameters

Parameter Description Required

Entity

Specify which entity you want to fetch a value from, for example Files (Cases).

Yes

Filter

Enter the key of the entity you want to get a value from. If you always want to fetch a value on the current case, which is the case on which the case activity is started, you can enter:

ID eq '{Case.ID}'

Tip: You can use WorkZone QueryBuilder to build your query and copy the filter part to this parameter. See How do you copy a query from WorkZone QueryBuilder.

Yes

Property

Specify the property that you want to fetch a value from. For example, if you want to get the case state, enter:

State_Value

Tip: You can use WorkZone QueryBuilder to find the name of the available properties.

Yes

QueryOptions

Specify OData query options, such as $top, $orderby, $aggregate, and so on. For example, if you have a list of cases and you want to fetch the second to last case, enter:

$OrderByDesc=ID$skip=1, which will sort the cases in descending order and skip the first case in the list.

See Use query options.

No
Example: The example below illustrates the use of the GetValue activity effect together with guards. A date is fetched from the Created property on the current case and compared with a date fetched from the PlannedCompleted property. The dates are compared using the guards. If the condition in the guard is met, a hearing process is started.

The DCR process looks like this:

Activity1 (GetValue from Created field) fetches the date from the Created field on the current case. The parameters are defined as follows:

Activity2 (GetValue from PlanCompleted) fetches the date from the PlanCompleted field on the current case. The parameters are defined as follows:

The Include and Exclude relation types have guards that compare the dates.

  • Include relation type:

    • Activity1<Activity2

  • Exclude relation type:

    • Activity1>Activity2

If the date fetched by activity1 is less than the date fetched by activity2, the subsequent activity will be included, in this example a StartProcess activity is executed, which starts a hearing process. If the condition is not met, nothing will happen.

Note: Do not use @Me or @Unit in the GetValue activity. The GetValue activity is always executed automatically by a system user, and therefore @Me and @Unit will fail. See Execute activities automatically.

SetValue

SetValue allows you to set a value based on a query in a WorkZone field. You can use the Computations field on the SetValue activity to provide an expression, for example combining a GetValue activity and actual values. The value that is calculated in the Computations field, will be the value that will be set in the specified WorkZone field.

Return value

The return value of the SetValue effect is the property. See Reference values from DCR activities for information on how you can reference return values in other activities.

Empty fields and computations

If a field that is used as a basis for computations in DCR process is empty, some computations based on that field can result in an error with the error message similar to the following error message (triggered for some computations involving date and time): Conversion is not supported from type DCR.Time.Duration to Odata type [Edm.DateTime Nullable=True]

As the type of the result of the computations must match the type of the property it will be assigned to, for example integer fields with integer types and DateTime fields with DateTime types, using an empty field as a basis for calculation operations can result in an conflict of field types and thereby trigger the error.

SetValue parameters

Parameter Description Required

Entity

Specify on which entity you want to set a value, for example Files (Cases).

Yes

Filter

Enter the key of the entity. If you always want to set a value on the current case, which is the case that the case activity is started on, you can enter:

ID eq '{Case.ID}'

Tip: You can use WorkZone QueryBuilder to build your query and copy the filter part to this parameter. See How do you copy a query from WorkZone QueryBuilder.

Yes

Property

Specify the property that you want to insert the value in to. For example, if you want to set a date in the Planned completed property, enter:

PlanComplete

Tip: You can use WorkZone QueryBuilder to find the name of the available properties.

Yes

MaxEntitiesTo Update

The maximum number of entities that the activity can set. For example, if you set this parameter to 10, and your query results in 10 cases or less, all cases will be updated. If the result of the query exceeds the maximum, the activity will fail , and an error message will be shown in the history.

Yes
Example: In this example, the created date of the current case is retrieved using a GetValue activity. The Created value is used to calculate the planned complete date which will be 7 days later. The new date will be stored in the PlannedComplete property on the case.

The DCR process looks like this:

Activity0 (GetValue from Created field) fetches the date from the Created field on the current case. The parameters are defined as follows:

Activity1 (Insert computed value to PlanCompleted) sets the new date in the PlanCompleted property on the current case based on the calculation of the date in the Computations field of the SetValue activity. The parameters are defined as follows:

In the Computations field of the Activity0, insert Activtity0 + P7D, which results in a value (Created date plus 2 days) that will be stored in the PlanCompleted property, when the SetValue activity is executed.