kwizcom custom actions app admin guidecatalog.kwizcom.com/sites/pc/product documentation...when...

KWizCom Corporation

KWizCom Custom Actions App

Admin Guide

KWizCom Custom Actions Admin Guide

Copyright © 2005-2018 KWizCom Corp. All rights reserved. www.kwizcom.com | of 28

Copyright © 2005-2018 KWizCom Corporation. All rights reserved.

Company Headquarters

95 Mural Street, Suite 600

Richmond Hill, ON

L4B 3G2 Canada

E-mail: [email protected]

Web site: http://www.KWizCom.com

Sales

E-mail: [email protected]

Telephone: +1-905-370-0333

http://www.kwizcom.com/ProductReg

http://www.kwizcom.com/



CONTENTS

Contents ........................................................................................................................................................................ 3

Product Overview .......................................................................................................................................................... 4

Key Features .............................................................................................................................................................. 5

Administration Guide .................................................................................................................................................... 6

Custom Actions and Activities ................................................................................................................................... 6

Steps required to implement a use-case ................................................................................................................... 8

Managing Activities ................................................................................................................................................... 9

Activities settings page ........................................................................................................................................ 10

Create/Edit Activity .............................................................................................................................................. 11

using dynamic tokens and variables in activities ................................................................................................. 15

Managing custom actions ........................................................................................................................................ 16

Custom Actions settings page .............................................................................................................................. 17

Create/Edit Custom Action .................................................................................................................................. 18

binding variables in custom actions..................................................................................................................... 25

custom action History .............................................................................................................................................. 27




PRODUCT OVERVIEW

KWizCom Custom Actions App is part of KWizCom Forms App (Enterprise edition).

With Custom Actions you can easily 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 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 design tools.




KEY FEATURES

Main key features of KWizCom Custom Actions are:

Feature KWizCom Custom Actions

Custom item-level actions √

Custom action includes a sequence of conditioned activities √

Context-sensitive/conditioned actions √

Trigger an action with custom ribbon buttons √

Trigger an action when item created, updated, deleted √

Automatically create, update and delete items √

Copy item activity √

Call web service activity √

Send email activity √

Call workflow activity √

Run-time variables enabling passing data between activities √

Cross-browser support: IE, Firefox and Google Chrome √




ADMINISTRATION GUIDE

This section describes the steps needed to implement use-cases by using KWizCom Custom Actions.

CUSTOM ACTIONS AND ACTIVITIES

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.

Custom Action implements a use-case (which is process) and is triggered by user-click or automatically

be other events. Each custom action includes a series of conditioned activities, enabling you to

implement your required use-case.




The following image describes the connection between a Custom Action and Activities:




STEPS REQUIRED TO IMPLEMENT A USE-CASE

This section describes what you should do by order in order to implement a business use-case.

We will use the following example use-case:

We have an “Orders” list. We wish to implement an “Approve Order” custom action.

When user approves an order, the following should happen:

- The ordered amount should updated in the Inventory system (by using a webservice call)

- An email should be sent to the customer, advising that his order has been approved

Implementing a use-case is done in the following order:

1. Identify the activities required for your custom action

In our example above, we have identified 2 activities that need to be created:

• Update Inventory

This will be a webservice activity that will call the “Inventory” system’s web service to

update the ordered quantity.

• Send Email

This activity will send the mentioned email message above.

2. Create these activities

3. Create the custom action that calls these 2 activities one after the other

In the next section we’ll explain how to create activities and custom actions, using KWizCom Forms App

settings pages.




MANAGING ACTIVITIES

To get to the Activities settings page, in the KWizCom Forms landing page, click” Activities”:

You will be redirected to the Activities settings page.




ACTIVITIES SETTINGS PAGE

This page includes the following fields:

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

CREATE/EDIT ACTIVITY

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


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.


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:

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:


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.

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.


http://goessner.net/articles/JsonPath/



USING DYNAMIC TOKENS AND VARIABLES 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

- 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 “emailVar” 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.




MANAGING CUSTOM ACTIONS

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.




CUSTOM ACTIONS SETTINGS PAGE

This page includes the following fields:


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.

CREATE/EDIT CUSTOM ACTION

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


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:

Now, you can add activities to this group as well as configure conditions for this group of activities to be called.

In the following example the 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 define the conditions that must be met for the custom action to run (if automatic) or be visible to

end-users (if a ribbon button).

When providing values for conditions you can also 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 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.

Now, when adding this activity to a custom action we can see that the “newStock” variable appears as a

blue link:

Now, 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.




CUSTOM ACTION HISTORY

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.


kwizcom custom actions app admin guidecatalog.kwizcom.com/sites/pc/product documentation...when...

Documents