Custom Actions App is part of KWizCom Forms App (Enterprise edition).
With Custom Actions you can implement business use-cases without messing with technical workflow design tools, this way non-technical users such as site owners can implement their required use-cases.
Custom Actions App enables you to:
- Add custom ribbon buttons that will trigger a sequence of activities
- Automatically trigger a sequence of activities upon item event (such as when item is created or updated)
Implementing custom actions is done by using easy-to-use web settings pages, so there’s no need to install or learn any complex workflow design tools.
When you open the KWizCom Forms landing page you will see these 2 menus (Enterprise edition):
Activities are atomic and 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 or automatically by other events. Each Custom Action includes a series of Activities, enabling you to implement your required use-case.
The following image describes the connection between a Custom Action and Activities:
Creating a workflow 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 KWizCom Forms landing 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 | Filtering activities by type | These links enable you to filter the existing activities by their type.
by default the “All Activities” filter is selected so you see all existing activities for the current list. |
| 3 | Existing activities | Existing activities appear one below the other, where for each activity you see: - Its type (icon) - Name - Description |
| 4 | Activity options | For each activity you have the following graphic buttons:  Which are for editing, cloning and deleting an activity. |
| 5 | “Manage custom actions” button | Click to open the Custom Actions settings page in a new tab. |
When creating a new activity or editing an existing activity you will see the “Edit Activity” page, which has 2 tabs:
“Activity Settings” and “Properties”.
Activity Settings tab
| # | Property | Description |
| 1 | “Activity Type” field | This drop-down displays all available activity types that you can use. The available types are: Add Item – Add an item to the current list or another list. Copy Item - Copy an item to the current list or another list. The copied item can be the current item or an item selected by using a query. Delete Item – Deletes current/other item. Email – Sends an email Get Column Value – Get a column value from an item in a list. The value is stored in an output variable. Update Item – Update an item in the current list or another list. The updated item can be the current item or an item selected by using a query. Webservice – Call a rest webservice and return a single value. Workflow - Start a workflow that is associated with the current list. |
| 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.
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
- Tokens: 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 “ToVar” 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 current item’s “Title” columns, and in the message body you can see 2 additional tokens getting their values from the current item’s “Assigned To” and “ID” columns.
This way you can have dynamic actions which get their property values in run-time.
To get to the Custom Actions settings page, in the KWizCom Forms landing page, click ”Custom Actions”:
You will be redirected to the Custom Actions settings page. This page includes the following properties:
| # | Property | Description |
| 1 | “new custom action” button | Click to create a new custom action. |
| 2 | Filtering custom actions by type | These links enable you to filter the existing custom actions by their type.
By default the “All custom actions” filter is selected so you see all existing custom actions for the current list. |
| 3 | Existing custom actions | Existing custom actions appear one below the other, where for each custom action you see: - Its type (icon) - Name - Description |
| 4 | Custom Actions options | For each custom action you have the following graphic buttons:  Which are for editing, activating/deactivating and deleting an activity. |
| 5 | “Manage Activities” button | Click to open the Activities settings page in a new tab. |
When creating a new custom action or editing an existing custom action you will see the “Edit Custom Action” page, which has 3 tabs: “Action Settings”, “Activities” and “Conditions”.
Action Settings tab
| # | Property | Description |
| 1 | “Custom Action Type” field | Choose the type of custom action: Automatic action – this actions is automatically triggered when item is added/deleted/updated. Ribbon Button Action – this action displays a custom ribbon 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” field | Check the event/s one which you want the custom action to be triggered. |
Additional properties for Ribbon Button Action type
| Property | Description |
| Button Caption | Check the event/s one which you want the custom action to be triggered. |
| Confirmation Message | If you want to prompt the user a verification message before the actions starts working, enter the verification text. |
| Icon Url (16px X 16px) | The displayed ribbon button’s icon. |
| Icon Url (32px X 32px) | The displayed ribbon button’s icon. |
| Redirect on complete | Set the URL that the user will be directed to when the custom action has completed. Once the action is done, it will redirect you back to the page you came from by default. Use this property to specify the page you wish users to be redirected once the action completes.
You can type a relative/full URL, you can also use the following tokens: [View Name] - will redirect to a defined list view [Default View] - will redirect to the list's default view [Home] - will redirect to the site's home page [View Item] [Tab Name] - will redirect to the current item's View Item page, if tab also defined - to the defined tab [Edit Item] [Tab Name] - will redirect to the current item's Edit Item form, if tab also defined - to the defined tab |
| Editable fields | Select the fields that can be edited by the end-user before the custom action executes.
This means that after end-user clicks the custom ribbon button he will see a custom form with the editable fields, after submitting that form the other custom action’s activities will run. This enables you to implement a flow that includes both user input and automatic activities. |
Activities tab
The “Activities” tab enables you to add activities that will be called by the custom action.
You have 2 ways of adding an activity to the custom action:
add activity
When clicking the “add activity” button you will see all available activities for the current list:
Simply click 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 “Update product inventory” 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
Sometimes you will need an activity or a group of several activities to run under a custom action only if some condition is met. To add an activity or group of activities that will be conditionally run, click the “add activity group with condition” button, this will add an 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
“Product” column’s value equals “Document Quick Previewer”.
Conditions tab
In this tab you configure the conditions that must be met for the custom action to run (if automatic)
or be visible by end-users (if a ribbon button).
When providing values for conditions you can also use dynamic tokens such as [column names], [Me] and [Today]
In the Activity settings page we introduced the concept of variable (formatted [%varname%]), which enable creating parametrized activities.
So, when does an activity get the value for its parameter?
This happens when you add the activity to a custom action.
In the following example we have the “Update Inventory” activity which updates the “Inventory” list’s “stock” column:
As you can see, it updates the “Stock” column with the value of [%newStock%] variable.
When adding this activity to a custom action we can see that the “newStock” variable appears as a blue link:
When clicking this link the “Variable Map Editor” popup opens, allowing you to select fields/formula to bind to this variable:
So you can select various variables, list ot 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 or ribbon button.
So 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 list item by clicking the “Custom Action History” ribbon button in the item’s view form:
Clicking I will open a popup showing the recent custom action/s called due to item event or ribbon button click:
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.