ToC

Table of Contents

What is a Call to Action? What Can Be Included in a Call to Action? Creating Calls to Action Using the Execution Engine Call to Action Methods Will the calls to action respect security? Creating Action Plan Items that Present a Choice Common Examples Change Phase Creating or Opening a Prepare Document Open URL Special note: Manage Participants Create a New Work Item Edit a Work Item Edit a Scorecard / Risk Profile Liability Details Manage Reserves Legacy Calls to Action

Using Calls to Action in Workflow

What is a Call to Action?

Calls to action (C2A) are created using Execution Engine plans, or workflows, as part of an action plan. For example, the blue Manage Participants button in the screen below is a call to action against a checklist action plan item. C2As provide links to quickly actioning the items prescribed in tasks.

What Can Be Included in a Call to Action?

A call to action can invoke any standard command in the ShareDo application and link to an external website. An Execution Engine plan author can configure the actions available for each item in their action list, including the call to action details, icon, colours, and other parameters.

This is an example piece of configuration for an action plan item created within an Execution Engine plan.

Creating Calls to Action Using the Execution Engine

Creating new C2As relies on the call to action builder available in execution plan snippets. The action plan item builder has a .WithCallToAction method that accepts a call to action object created using actions.sharedo.BuildCallToAction.

When you create a call to action, you reference a known command, specify its configuration, and optionally specify the ID of the thing against which you want to ultimately invoke the command—this is called the context type and context ID.

The context can be one of these types.

  • Global - A command that can be executed anywhere and does not need a reference to a work item, participant, or any other context type. E.g. open a web page, create a new work item (with no parent).
  • Work Item - A command that can be executed against a work item. This requires a context ID - the ID of the work type that it's executed against. E.g. manage participants for a work item, create a new work item (with the current work item as a parent), change phase.
  • Participant - A command that can be executed against a participant on a work item. This command requires the participant ID of the participant against which it is being executed. Note that this is against a participant, not against the particular role they hold on the work item. E.g. edit participant, re-assign one or more of the participant roles.
  • Participant Role - A command that can be executed against a participant role on a work item. This requires a context ID - the ID of the role it's executed against. Note that this is against one role for the participant - if they hold multiple roles, each role has a different context ID.

Mirroring these context types, the call to action builder offers methods to construct commands based on those contexts. To create a new call to action to attach to an action plan item call:

actions.sharedo.BuildActionPlanItem()

Triggers allow an Execution Engine plan to be initiated. The application collects a large number of events, which can be used to trigger workflows.

An example of a trigger could be updating a task to complete.

Call to Action Methods

The call to action builder provides the following methods that can be invoked to control the appearance of the C2A button, set the command and build the C2A to pass to the action plan item builder.

Method Details

.WithDisplay(string text)

.WithDisplay(string text, string icon)

.WithDisplay(string text, string icon, string cssClasses)

Controls the display of the C2A button.

text: The text to appear in the button.

icon: A font awesome CSS icon such as “fa-cogs”.

cssClasses: Additional CSS classes to add to the button itself, such as “btn-warning” (A yellow/warning button), “btn-danger” (a red/danger button) etc.
.WithStyles(string cssStyles) Fine control over the CSS styles added to the button. Any valid CSS markup can be specified. E.g. “border: 10px solid red; font-size: 2rem”.

.WithCommand(string commandName)

.WithCommand(string commandName, object configuration)

 Attaches a context-less command to the C2A button with optional configuration.

.WithCommandForSharedo(string commandName, string sharedoId)

.WithCommandForSharedo(string commandName, Guid sharedoId)

.WithCommandForSharedo(string commandName, object configuration, string sharedoId)

.WithCommandForSharedo(string commandName, object configuration, Guid sharedoId)

Attaches a command with a sharedo context that will be built against the specified work item with optional configuration.

Note the ID can be passed as either a string or a native GUID.

.WithCommandForParticipant(string commandName, string participantId)

.WithCommandForParticipant(string commandName, Guid participantId)

.WithCommandForParticipant(string commandName, object configuration, string participantId)

.WithCommandForParticipant(string commandName, object configuration, Guid participantId)

Attaches a command with a participant context that will be built against the specified participant with optional configuration.

Note the ID can be passed as either a string or a native GUID.

.WithCommandForParticipantRole(string commandName, string participantRoleId)

.WithCommandForParticipantRole(string commandName, Guid participantRoleId)

.WithCommandForParticipantRole(string commandName, object configuration, string participantRoleId)

.WithCommandForParticipantRole(string commandName, object configuration, Guid participantRoleId)

Attaches a command with a participant role context that will be built against the specified participant role with optional configuration.

Note the ID can be passed as either a string or a native GUID.
.Build() Completes building the C2A and returns the structure to the action plan item builder.

Will the calls to action respect security?

Yes—if the call to action invokes a command the user viewing the action plan does not have permission to use, the button will not appear. For example, if the call to action involves creating a new work item of a type the user has no permission to create, the button will be hidden.

Creating Action Plan Items that Present a Choice

Calls to action can offer your users a variety of action plans, allowing them to select an option. When defining these calls to action, you can emphasise the buttons to encourage your user to make the 'right' choice. Each option can have its own call to action if required.

var newChoice2 = actions.sharedo.BuildActionPlanItem()
	.WithDescription("New choice - improved API")
	.AddChoice("option1", "Option number 1", actions.sharedo.BuildCallToAction()
		.WithDisplay("SP OP NO 1", "fa-cog", "btn-danger")
		.WithCommand("start-service-portfolio", {
			title: "New instruction 1",
			mode: "client-portal"
		})
		.Build())
	.AddChoice("option2", "Option number 2", actions.sharedo.BuildCallToAction()
		.WithDisplay("SP OP NO 2", "fa-cogs")
		.WithCommand("start-service-portfolio", {
			title: "New instruction 2",
			mode: "client-portal"
		})
		.Build())
	.AddChoice("option3", "Option number 3", actions.sharedo.BuildCallToAction()
		.WithDisplay("SP OP NO 3")
		.WithCommand("start-service-portfolio", {
			title: "New instruction 1",
			mode: "client-portal"
		})
		.Build())
	.Build();

Common Examples

The following are common examples of calls to action.

Change Phase

Command Action
sharedo-change-phase Opens the phase transition screen for the specified work item. 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("New")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Change phase", "fa-sitemap")
		.WithCommandForSharedo("sharedo-change-phase", ctx.sharedoId)
		.Build()
	)
	.Build();

Creating or Opening a Prepare Document

If you want to create or open a prepare document with some pre-configured information.

Command Action
sharedo-open-or-create-task

As above, the new commands create or edit a task work item with the context ID as the parent or open the existing one for editing if one has already been created from the action plan.

The new command consolidates the above by allowing additional configuration.

  • Allows the template system name to be set.
  • Allows the document class to be set.
  • Can set regarding as well as recipient.
  • Can allow for single instance tasks to be created under the parent, regardless of which C2A created it (though can still have single instance tasks per action plan item, action plan etc.).

The configuration object is defined as shown below.

 
{
	instanceTag: "there-can-be-only-one",
	sharedoType: "task-activity-prepare-document",
	assignToHolderOfRole: "client",
	title: "Prep doc test 1",
	dueOffset: "+1h",
	prepareDocument: {
		template: "top-and-tail-letter",
		documentClass: "Correspondence",
		recipientRole: "client",
		regardingRole: “claimant”
	},
	parameters: {
		assignToOdsId: ctx.creator.odsId,
		recipientId: null,
		recipientLocationId: null,
		regardingId: null,
		dueDate: null
	}
}

When created as a call to action, there are more parameters available to the author than would be the case if the command were attached to a menu.

Property Details
instanceTag

One of the purposes of this command is to enforce that a task is either created, or if it exists, is opened instead. instanceTag controls this – when set to any string, rather than creating a new task, it will first attempt to find any work item of the same sharedoType as a child of the parent with this same instanceTag – if it finds one, it will open it instead of create it.

This allows multiple C2A’s, even across different action plans, to ensure there is only one instance of a work item created for its purposes.
sharedoType This should be set to the type of work item to create. This should derive from /task/ given it intends to use the task API to create the item.
assignToHolderOfRole

Defaults to empty.

Set this to a role system name. When the command creates the new work item, it will attempt to find a holder of this role on the work item context for which it is being built and, if found, will set that participant ODS ID to be the primary owner of the task.

If no role is specified or no role can be found on the context work item, the current user is assigned as primary owner.

If the extended C2A parameter (parameters.assignToOdsId) is not null, that ODS ID will be assigned primary owner instead.
title The title of the new task.
dueOffset

The offset to use when calculating the new task’s due date. Can be any valid duration offset string such as +1d.

If the extended C2A parameter (parameters.dueDate) is not null, it will be used for the due date instead and the due offset will be ignored.
prepareDocument This structure is used when the task to create represents a prepare document.
prepareDocument.Template The system name of the document template to associated with the new task.
prepareDocument.documentClass The document classification to set on the prepare document task, which will control where the output document is stored in the document management system.
prepareDocument.recipientRole

When this is set to a system name of a participant role, when the system is creating the task, it will inspect the context work items participants for the first participant holding this role. That participant will be set as the recipient in the new prepare document task.

Similarly, if the holder of that role has a location associated with the context work item, it will also reference the same address.

If parameters.recipientId is set, this setting is ignored and the recipient is set directly to the ID specified there. The same also applies to parameters.recipientLocationId
prepareDocument,regardingRole

As per recipientRole above, setting this to the system name of a participant role will link the holder of that role from the context work item to the regarding field on the new prepare document work item.

If parameters.regardinId is set, this setting is ignored and the regarding participant is set directly to the ID specified there.
parameters Represents additional configuration that is not available when attaching this command to menus etc. Action plan C2As can set these additional parameters to have more direct control over the task that is created.
paremeters.assignToOdsId

If this is set to an ODS ID, that user/team will be assigned as the primary owner of the task. Directly setting the primary owner offers more flexibility, but typically, a C2A will use the assignToHolderOfRole configuration instead to dynamically discover who to assign to.

If assignToOdsId and assignToHolderOfRole are both set, assignToOdsId will always take preference.
parameters.recipientLocationId

If this is set, it should be set to the participant ID of a participant on the context work item. The recipient on the generated prepare document task will be directly set to this value. Directly setting the recipient offers flexibility, but typically a C2A will use the prepareDocument.recipientRole configuration to dynamically discover who to write to.

If recipientId and recipientRole are both set, then recipientId will be used.
parameters.regardingId

If this is set, it should be set to the participant ID of a participant on the context work item. The regarding field on the generated prepare document task will be directly set to this value. Directly setting the regarding offers flexibility, but typically a C2A should use prepareDocument.regardingRole configuration to dynamically discover who we’re writing about.

If regardingId and regardingRole are both set, then regardingId will be used.
parameters.dueDate Directly set the due date and ignore the dueOffset setting. 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Send welcome letter")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Top and tail", "fa-check")
		.WithCommandForSharedo(
			"sharedo-open-or-create-task", {
				instanceTag: "there-can-be-only-one",
				sharedoType: "task-activity-prepare-document",
				assignToHolderOfRole: null,
				title: "Prep doc test 1",
				dueOffset: "+1h",
				prepareDocument: {
					template: "top-and-tail-letter",
					documentClass: "Correspondence",
					recipientRole: "client",
					regardingRole: "claimant"
				},
				parameters: {
					assignToOdsId: ctx.creator.odsId,
					recipientId: null,
					recipientLocationId: null,
					dueDate: null
				}
			},
			ctx.sharedoId
		)
		.Build()
	).Build();

Open URL

Command Action
open-url This consolidated command is configured to open any URL, optionally in a new window and optionally relative to the current portal being viewed. The configuration object is defined as follows: 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Check maps (new)")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Check Google Maps", "fa-search")
		.WithCommand("open-url", {
			url: "https://www.google.com/maps",
			openInNewWindow: true,
			portalRelative: false
		})
		.Build()
	)
	.Build();

Special note:

While there is a portalRelative option, its use is not recommended for calls to action as you may not be on the portal for the work item when you click the call to action button. As such, if attempting to provide a link to a page within a work item portal, the full URL should be constructed instead, and portalRelative set to false.

For instance, if you expect your C2A to navigate to the /actions page of the work item portal, construct the full URL as follows:

var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Review actions")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Open actions", "fa-check")
		.WithCommand("open-url", {
			url: "/sharedo/" + ctx.sharedoId + "/actions",
			openInNewWindow: false,
			portalRelative: false
		})
		.Build()
	)
	.Build();

This will then work even if the task and C2A are being viewed from the mysite portal or a portal for a completely different work item.

Manage Participants

Command Action
manage-participants Opens the manage participants blade for the context id specified. 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Add participants")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Manage participants", "fa-users")
		.WithCommandForSharedo("sharedo-manage-participants", ctx.sharedoId)
		.Build()
	)
	.Build();

Create a New Work Item

Command Action
create-sharedo Invokes the Add/edit sharedo blade to create a new work item of the specified type with the work type context ID as the parent and defaulting optional parameters. The configuration object is defined as follows: 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Test")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Create task", "fa-check", "btn-success")
		.WithCommandForSharedo(
			"create-sharedo", {
				typeSystemName: "task",
				useCurrentContextAsParent: true,
				title: "Title of the new item",
				description: "Some default description we want to add"
			},
			sharedoId
		)
		.Build()
	)
	.Build();

Edit a Work Item 

Command Action
create-sharedo

Opens the Add/Edit key facts blade for the specified work item ID.

Note: In future this will change to invoke the appropriate view command configured against the work type, which may not necessarily open the key facts blade (e.g. key dates use a different blade).

 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Test")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Key facts", "fa-check", "btn-success")
		.WithCommandForSharedo(
			"edit-sharedo",
			sharedoId
		)
		.Build()
	)
	.Build();

Edit a Scorecard / Risk Profile 

Command Action
edit-scorecard

Opens the edit scorecard blade for the given work item in the context ID. 
Note: you no longer specify the template ID to use – it will use the primary scorecard associated with the work item type (via the scorecard feature).

If no scorecard is defined for the work item type, the call to action will not be generated.

If the scorecard feature is not enabled for the work item type, the call to action will not be generated.

 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Test")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Edit Scorecard", "fa-check", "btn-success")
		.WithCommandForSharedo(
			"edit-scorecard",
			sharedoId
		)
		.Build()
	)
	.Build();

Liability Details 

Command Action
edit-liability

Opens the liability blade for the given work item ID in the context.

Note: if the liability feature is not enabled on the work item type, this command is not available and no call to action button will be created.

 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Test")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Edit Liability", "fa-check", "btn-success")
		.WithCommandForSharedo(
			"edit-liability",
			sharedoId
		)
		.Build()
	)
	.Build();

Manage Reserves 

Command Action
edit-reserves

Opens the manage reserves blade for the given work item ID in the context, with a specified account system name and mode. The configuration object is defined as:

{

“accountSystemName”: “[schedule-of-loss or other account type]”

}

 
var newC2A = actions.sharedo.BuildActionPlanItem()
	.WithDescription("Test")
	.AddCheckbox()
	.WithCallToAction(
		actions.sharedo.BuildCallToAction()
		.WithDisplay("Manage reserves", "fa-check", "btn-success")
		.WithCommandForSharedo(
			"edit-reserves", {
				accountSystemName: "schedule-of-loss"
			},
			sharedoId
		)
		.Build()
	)
	.Build();

Legacy Calls to Action

In legacy smart plans or early Execution Engine plans, calls to action used a unique identifier (guid) to determine which user interface element to call. For example:

This required the user to know that the guid (beginning “21C72…”) represented the manage participants button, which in turn would be constructed using the work type ID passed to it to eventually allow the manage participants blade to be opened against it (in this case, against the task’s immediate parent work item).

These legacy calls to action will continue to be supported in the next few releases.

Related Articles

Adding a call to action button - Workflow Toolbox

There are a number of places within workflow modeller where you may add in a chec...

Progress Milestone (Change Phase) - Workflow Toolbox

The progress milestone tool box item allows you to add the ability to change the ...

Business Rule - Workflow Toolbox

Within the toolbox, it is now possible to use the evaluation of a Business Rule t...