Skip Ribbon Commands
Skip to main content
Sign In

Custom Actions

Custom Actions


Feature Overview

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.

In the list's KWizCom Apps settings page you will see these 2 menus (Enterprise edition):

 




Managing Activities

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:

 

#

Property

Description

1

“new activity” button

Click to create a new activity 

2

Search

Search for activity by name

3

Existing activities

Existing activities for the current list

4

Activity options

For each activity you have the following options:

- Edit activity

- Copy activity

- Delete activity

 

Create/Edit 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

#

Property

Description

1

Activity Type

This drop-down displays all available activity types that you can use.

2

Name

Activity name.

3

Description

Describe the activity’s purpose, this text will be displayed to the user who uses the activity in a custom action.

 

 

Properties tab

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:

Activity type

Properties

Add item

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 item

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.

Fields to update – add the fields that you wish to update in this activity.

Delete item

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:

Move item

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.

Fields to update – add the fields that you wish to update in this activity.

Update item

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:

Fields to update – add the fields that you wish to update in this activity.

Email

Recipients – Enter valid email addresses (‘;’ delimited).

Subject – Type the email message’s subject,

Body – Type the email message’s body text.

IMPORTANT:

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

Value type - Select if the parameter user will include a user name/login, or a dynamic token such as a column name or variable.

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.

Property - Select the SharePoint Profile property name which you want to retrieve its value.

Set Item Permissions  

Update– Select if you want to update the current/other item's permissions.

If "Other item" selected, identify which item by updating the following 3 properties:
Target site*, Target list – select the site and list where the other item is located.

Query – this section allows you to indicate which item you wish to update by setting a property-based criteria:

 

Remove existing permissions - Check this checkbox if you want to remove all existing permissions before applying new ones.
Permission level - Select the required permission level 
Value type - Select if the parameter user will include a user name/login, or a dynamic token such as a column name or variable.
  

Web Service

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

Workflow Name – select/type the workflow name that you want this activity to trigger.

 

 
* IMPORTANT:
The “Target site/Source site” drop-down will display all sites in the current site collection, depending on the current user’s permissions. If the current user does not have access permissions to the top-level site, then this drop-down will display only sites that are below the current site.

 

Using dynamic tokens in activities

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].

Example:

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.

 

 

Managing Custom Actions

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:

Actions tab

#

Property

Description

1

“new action” button

Click to create a new custom action.

2

Search

Search for an action by name.

3

Existing custom actions

Existing custom actions for teh current list.
For each custom action you see:

-  Its type (icon)

-  Name

-  Description

4

Custom Actions options

For each custom action you have the following options:

- Activate/deactivate action

- Edit action

- Copy action

- Delete action

Default actions tab
This page is used to select custom actions that should replace the New/Edit item forms. 
See more details about Default actions.
 

Create/Edit Custom 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”.

Settings tab

This is where you set the activity's name and select the type of action.

 

#

Property

Description

1

Action Type

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.

2

Name

Custom action name.

3

Description

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)

4

Enabled

Check to make the custom action active (visible to end-users)

 

 

Additional properties for Automatic Action type:

 

Property

Description

Run on events

Check the event/s one which you want the custom action to be triggered.

 

Additional properties for User Action type:

Property

Description

Button Caption

A User action displays a custom button in the New/Edit/View form toolbar, this is the caption displayed for the button.

Confirmation Message

If you want to prompt the user a verification message before the actions starts working, enter the verification text.

Button Icon

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.

Editable fields 
This property is displayed when "Show edit form before running this action " is checked.
Select the fields that can be edited by the end-user before the custom action executes.
This enables you to implement a flow that includes both user input and automatic activities.

 

Activities tab

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:

add activity

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”:

 
 

 

Conditions tab

 

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]



 

Binding variables in custom actions

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.

Default Actions

User actions that display a form, can replace the default New/Edit item forms.
This enables you to override the regular New/Edit Item forms, and offer the end-user with alternative forms, according to the current use-case.
In the Custom Actions settings page, click the "Default actions" tab:
Example:
In the "Travel requests" list we have 2 user actions, each displays selected fields and calls an activity that updates other selected fields

When an end-user creates a new travel request, we want to show him the relevant form and auto-update some fields, depending on the type of travel.
In the "Default actions" tab, we select these 2 actions as default actions for the New Item form:
Now, when end-user clicks the list's "New Item" button, the following popup will appear instead of the regular New Item form:
Selecting one of these user actions will display the selected action's form and will run that action's activities after the item is created.
 
 

 

Custom Action History

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.

 

 

Created at 4/18/2022 5:47 AM by Nimrod Geva (UTC-05:00) Eastern Time (US and Canada)
Last modified at 4/24/2022 10:47 AM by Nimrod Geva (UTC-05:00) Eastern Time (US and Canada)
Total Views: 582

Tags

Article Type: User-guide
Recent Discussions
There are no items to show in this view.