Custom Actions feature is part of KWizCom Modern Forms (Enterprise edition).
With the Custom Actions feature you can automate business use-cases (Workflows) without messing with technical workflow design tools.
Implementing your required workflow involves 2 features: Activities and Custom Actions.
Activities are reusable tasks, each activity does a single specific thing (example: send an email). Custom Action implements a use-case (a process) and is triggered by user-click (User actions) or automatically by other events (Automatic actions). Each Custom Action includes a series of Activities, enabling you to implement your required use-case (workflow).
The following image describes the connection between a Custom Action and Activities:
Creating a workflow in your SharePoint list/library is done by first creating the required Activities and then creating a Custom Action, which triggers those activities according to a configured logic.
To get to the Activities settings page, in the list's KWizCom Apps page, click ”Activities”:
You will be redirected to the Activities settings page. This page includes the following properties:
“new activity” button
Click to create a new activity
Search for activity by name
Existing activities for the current list
For each activity you have the following options:
- Edit activity
- Copy activity
- Delete activity
When creating a new activity or editing an existing activity you will see the “Edit Activity” page, which has 2 tabs:
“Settings” and “Properties”.
Activity Settings tab
This drop-down displays all available activity types that you can use.
Describe the activity’s purpose, this text will be displayed to the user who uses the activity in a custom action.
The “Properties” tab displays the selected activity type’s propertis, so depending on what type you’ve selected you will see different properties.
The following table outlines the properties displayed for each activity type:
Target site*, Target list – select the site and list that you wish to add an item to.
Fields to update – add the fields that you wish to update in this activity.
For each field fill-in the value that you want to update.
Copy – Select what item you want to copy: current or other.
Source site*, Source list – select the site and list that you wish to copy an item from.
Query – this section allows you to indicate which item you wish to copy by setting a property-based criteria:
Target site, Target list – select the site and list that you wish to add an item to.
Delete - Select what item you want to delete: current or other
Target site*, Target list – select the site and list that you wish to delete an item from.
Query – this section allows you to indicate which item you wish to delete by setting a property-based criteria:
Update - Select what item you want to update: current or other
Target site*, Target list – select the site and list that you wish to update.
Query – this section allows you to indicate which item you wish to update by setting a property-based criteria:
Recipients – Enter valid email addresses (‘;’ delimited).
Subject – Type the email message’s subject,
Body – Type the email message’s body text.
Before you can use the Email activity you need to visit KWizCom Apps Foundation settings page and ensure that the email server settings are configured. The link is available in the Email activity settings page.
Get Column Value
Get - Select from which item you want to get a column value: current or other
Target site*, Target list – select the site and list that you wish to get item column value from.
Query – this section allows you to indicate which item you wish to get a column value from by setting a property-based criteria:
Column to retrieve – select the column which its value you want to retrieve.
Get User Group Membership
Get User Profile Property
Value type - Select if the parameter user will include a user name/login, or a dynamic token such as a column name or variable.
Set Item Permissions
Update– Select if you want to update the current/other item's permissions.
Query – this section allows you to indicate which item you wish to update by setting a property-based criteria:
Method – Select http method GET/POST
Endpoint – Type the web service’s address (endpoint), you can then click the “TEST” button submit a request to your web service.
add authentication – click to add user/password in case your websrevice requires authentication.
add query string parameter – click to add parameters that you want to be sent as part of your GET request’s querystring parameters.
add post data parameter - click to add parameters that you want to be sent as part of your HTTP request’s body.
JSONPath – the webservice activity should return a single value, so in case it returns more than just a single value, you should use jasonpath expression to select the required value from the JSON response.
For more information about jasonpath please visit this link.
Output Type – Select the web service’s return type: text, number or boolean. Later when using this activity in a custom action you need to make sure you use this value with variables/columns of the same type.
Workflow Name – select/type the workflow name that you want this activity to trigger.
In the previous section we reviewed the Activity settings pages which enable you to create activities of various types and each activity type has its relevant properties.
In addition to selecting or manually typing a value in activity property, you can also use dynamic values of the following types:
- Variables: Variables enable parameterization of activities and provide the value for these parameters when binding the activity to a custom action. This allows creating more generic activities that can be better reused. To create a variable when creating/editing an activity type a variable name in the following format: [%variableName%]. You can then use that variable when adding the activity to a custom action and in conditions. Variables can only be used when editing activities
- Column values: With tokens you can use columns values by using square brackets and the column name, for example: [Due Date].
The following Email activity was configured as you see in the following screenshot:
The activity will send the email to address defined by “to” variable, which will get its value in run-time from the calling Custom Action (see details in the next section). The email message subject will get its value from the "Subject1" variable value, and in the message body you can see several additional variables - all will get their values from the calling Custom Action in run-time.
To get to the Custom Actions settings page, in the list's KWizCom Apps page, click ”Custom Actions”:
You will be redirected to the Custom Actions settings page. This page includes the following parts:
“new action” button
Click to create a new custom action.
Search for an action by name.
Existing custom actions
Existing custom actions for teh current list. For each custom action you see:
- Its type (icon)
Custom Actions options
For each custom action you have the following options:
- Activate/deactivate action
- Edit action
- Copy action
- Delete action
When creating a new custom action or editing an existing custom action you will see the “Configure Custom Action” page, which has 3 tabs: “Settings”, “Activities” and “Conditions”.
Choose the type of custom action:
Automatic action – this action is automatically triggered when item is added/deleted/updated.
User action – this action displays a toolbar button in the item’s New/Edit/View forms. Clicking the button triggers the custom action.
When selecting each of these types, the form displays additional fields, see details in the next section.
Custom action name.
Describe the custom action’s purpose, this text will be displayed to the end-user when hovering the custom ribbon button (relevant only for custom ribbon button type)
Check to make the custom action active (visible to end-users)
Additional properties for Automatic Action type:
Run on events
Check the event/s one which you want the custom action to be triggered.
Additional properties for User Action type:
A User action displays a custom button in the New/Edit/View form toolbar, this is the caption displayed for the button.
If you want to prompt the user a verification message before the actions starts working, enter the verification text.
The displayed button’s icon.
Redirect on complete
Use this property to specify the page you wish users to be redirected once the action completes. You can type a relative/full URL and you can also use various tokens by clicking the "+ insert token" drop-down.
Show edit form before running this action
Check this property if you want to display a form where user updates selected field values required by the custom action.
In the “Activities” tab you select the activities that will be called by the custom action.
You have 2 options for adding activities to the custom action:
When clicking the “add activity” button you will see all available activities for the current list:
Select the activity that you want to run under this custom action, and you will see its details added to your settings page:
In the screenshot above we have added the “Add Order” activity. You can see for this added activity its name and its exact definition.
The activities you add this way will be called one after the other according to their order.
add activity group
Activity group is a collection of 1 or more activities that need to be called only if a condition is met.
To add an activity group click the “add activity group” button, this will add an empty activity group to the page:
You can now add activities to this group as well as configure conditions for this group of activities to be called.
In the following example the activity group includes 2 activities, which will be called by the custom action only if “Status” column’s value equals “Customer approved”:
In this tab you configure the conditions that must be met for the custom action to run (if automatic action) , or be visible by end-users (if a User action). When providing values for conditions you can use dynamic tokens such as [column names], [Me] and [Today]
In the Activity settings page we introduced the concept of variables (formatted [%varname%]), which enable creating parametrized activities.
So, when does an activity get the value for its variables? This happens when you add the activity to a custom action.
In the following example we have the “Add Order” activity which updates the “Orders” list’s Customer, Product and Quantity columns:
As you can see in the screenshot above, it updates the Customer column with the value of [%cust%] variable.
When adding the "Add Order" activity to a custom action we can see these variables appear as hyperlinks:
When clicking a variable's link the “Variable Map Editor” popup opens, allowing you to select fields/formula to bind to this variable:
So you can select various tokens, list or site properties and bind them to the variable. This means that in run-time, when the custom action runs and calls the activity it will send this bound value to the activity as parameter.
Once you have saved your settings, your custom actions should run, depending of course on their type: automatic actions or user actions.
How can you know if your custom action executed successfully?
How can you know if one or more of its included activities failed?
You can see the custom action log for a selected list item by clicking the “Custom action history” sub menu in the item’s view form:
This will open a popup showing the item's custom actions log:
As you can see, below the custom action you can see all its included activities, and the execution status for each one. This gives you a clear picture of which activity met its conditions and the overall execution status of the custom action.