NewOpportunityForCompany
An example for a slightly complex process.
This is an example for a slightly more complex process that creates an opportunity (Y1) for a company (FI) and allows users to add opportunity participants (Y2) at a later time. The process consists of two phases, it contains a header, a Process Ask configuration and (phase) metrics and uses different data providers and process storage variables.
The process can be called from both the application menu and an existing opportunity's context menu.
The following graphic displays the process flow, the phases and steps and which actions they call.
The following chapters list the necessary configuration units.
Process NewOpportunityForCompany
- Create a new process called
NewOpportunityForCompany
.Since your process contains phases you do not need to specify an Initial Step.
- The Header drop-down list lists all info area-independent special headers.
- For the process metrics define a custom Data Provider
curTexts
loading the text group containing the multilingual texts used in the process.- Enter a Name.
- Define an Action using the built-in
external data provider
UsingDataProvider
. For further details, see UsingDataProvider. - Enter the name of the desired text group as argument
texts
. - Click Apply.
- Define following process storage variables:
-
curFIUid
: The uid of the company record for which the opportunity is created.If the process is started from the context menu of an existing opportunity the company uid is not needed and not passed to the process.
If the process is started from the application menu, the uid comes from the initial step where the user selects a company. For further details, see Step SelectFIForY1.
This is handled automatically by the process, you do not need to define conditions in this case.
-
curY1Uid
: Theuid
of the opportunity record.If the process is started from the context menu, the uid comes from the current opportunity, therefore Data Provider = Input Message (
$.get('uid')
).If the process is started from the application menu, the uid comes from the step where the user creates a new opportunity. For further details, see Step CreateY1.
-
curY2Count
: This variable is calculated by an evaluation step and used for the ProcessAsk page. For further details, see Step EvalY2Count and Step ProcessAskY1. Therefore initial value = 0. SincecurY2Count
is accessed at different points of the process, it must be defined in the process storage. -
repMetric
:$t('TXT_Process_TextGroup_0')
gets text number0
of text groupProcess_TextGroup
. Syntax,. For further details, see Referencing Texts in JavaScript. The text group has been loaded by the custom Data ProvidercurTexts
. -
curRepName
: The name of the current rep. Available functions for identifying the current rep. For further details, see u8.session.identity.
-
- To display the text "Rep: <current rep>" as a process metric, a
multilingual label and a variable value are combined as
$.get('repMetric')+$.get('curRepName')
. In an English-only environment you could just define"Rep: "+$.get('curRepName')
instead.repMetric
has been defined as a process storage variable because texts from different data providers can not be combined in one value definition.Alternatively, you could define two text metrics, one getting the label directly from data provider
curTexts
and the second getting the rep name from the process storage.In this case the texts are displayed in two lines.
Phase CreateY1
Define the first phase (selecting a company and creating an opportunity):
- Under Process Phases click (Add).
- Enter a Phase Name.
- Enter a Phase Label. This is displayed on the phase arrow.
- Select the phase's Initial Step. For further
details, see >> Step SelectFIForY1.Note: You need to create the steps before you can select them.
Once you have selected a step you can click (Edit) to edit the step.
- Define the conditions for the phase to be active:
!$.get('curY1Uid')
Phase
CreateY1
is only active/can only be activated if no opportunity exists, i.e. if called from the context menu of an opportunity, the process automatically starts with phaseAddY2
. - Define a phase metric using the PercentageTrafficLight View
with Value
!!$.get('curY1Uid')?50:0
Once an opportunity
uid
is present in the process storage, the traffic light changes to yellow. - Click Apply.
- You need to (re-)save the process, otherwise the phase definition is lost.
Phase AddY2
Define the second phase (adding opportunity participants):
- Initial Step:. For further details, see Step EvalY2Count
-
Condition:
!!$.get('curY1Uid')
Phase
AddY2
is active/can be activated if an opportunity exists. - Phase metric:
$.get('curY2Count')==0?0:100
The traffic light changes to green as soon as at least one opportunity participant has been added (
curY2Count
> 0).Each time the phase is activated, the process storage variable
curY2Count
is (re-)calculated by the phase's initial stepEvalY2Count
.
Step SelectFIForY1
- Create a step called
SelectFIForY1
allowing the user to select (or create) a company for which to create the opportunity. - Define the action: In this case a sub-step is called
(
ExecuteSelectRecordSubStep
) that uses the existing stepSelectCompany->Return
.ExecuteSelectRecordSubStep
returns theuid
of the selected record. For further details, see ExecuteSelectRecordSubStep. - To pass the
uid
of the selected FI record to the next step you need to define an output argument for the step: Theuid
is written to the process storage variablecurFIUid
. This is necessary since the process can be started with and without context, i.e. parent record. If the process is started from an existing opportunity,curFIUid
comes from the Input Message. For further details, see Process NewOpportunityForCompany. - Create the Next Step, see Step CreateY1. Since there is only one possible next step creating the opportunity, enter "true" as dispatching "condition".
Step CreateY1
- Create a step called
CreateY1
allowing the user to create a new opportunity. - Select the action (
ExpandNew
) and define its input arguments:-
infoAreaID
:Y1
-
link
: Since the process can be started with and without context, the opportunity's parent (FI) must come from the process storage:$.get('curFIUid')
-
- To read the RepID from FI and write it to RepID in Y1 you need to define a custom
data provider
curFIRep
for this step:- Enter a Name.
- Define an Action using the built-in
external data provider
ReadRecordDataProvider
. For further details, see ReadRecordDataProvider. - Get the
uid
of the record to read from the process storage:$.get('curFIUid')
- Enter the IDs or XML names of the fields to be read.
- Click Apply.
- Define the input arguments
defaultValues
anddefaultFields
. For further details, see defaultFields/defaultValues.- Get
defaultValues
from the custom data providercurFIRep
:$.get('RepID')
- Enter the IDs or XML names of the target fields as
defaultFields
- Get
- To pass the
uid
of the created Y1 record to the next step you need to define an output argument for the step: Theuid
is written to the process storage variablecurY1Uid
. This is necessary since the process can be started with and without context, i.e. parent record. If the process is started from an existing opportunity,curY1Uid
comes from the Input Message. For further details, see Process NewOpportunityForCompany. - Define the Dispatching:
- Enter the condition:
$.get('command')=='Save'
Saving the record navigates to the next step.
- Select "Step" as data provider (Source).
- Create the Next Step, see Step ProcessAskY1.
- Enter the condition:
Step ProcessAskY1
- Create a step called
ProcessAskY1
displaying the previously created opportunity and ask the user to create opportunity participants. For further details, see ProcessAsk. As soon as at least one participant is added, the user can exit the process. - Select the action (
ProcessAsk
) and define its input arguments:- The
name
of the Process Ask configurationProcessAskY1
. For further details, see Process Ask Configuration ProcessAskY1
Get the necessary parameters for the Process Ask page from the process storage:
- the opportunity record's
uid
for the Expand view - the current participants count (
Y2Count
) for the text -
Y2State
evaluating if the minimum number of participants has been reached - only then the process can be completed.
- The
- Define the Dispatching depending on the buttons defined in
the Process Ask configuration:
- Event 1: The user clicks the Add Participant button.
This calls
CreateY2
as Next Step. - Event 2: The user clicks the Show
Opportunity button. This calls
ViewRecord->Exit
and ends the process. For further details, see ViewRecord->Exit.Since a
ProcessAsk
step does not provideuid
as output argument you need to get theuid
forViewRecord->Exit
from the process storage:
- Event 1: The user clicks the Add Participant button.
This calls
Step SelectKPForY2
- Create a step called
SelectKPForY2
allowing the user to select (or create) a person to be added as opportunity participant. - Define the action: Analogous to
SelectFIForY1
a sub-step is called (ExecuteSelectRecordSubStep
) that uses the existing stepSelectPerson->Return
. It returns theuid
of the selected person record. - Define the Dispatching: Since there is only one possible next step (creating the opportunity participant), enter "true".
- Create the next step, see Step CreateY2. Pass the
uid
of the selected person and the opportunity (parent of opportunity participant) toCreateY2
:- Click (Edit step arguments).
You get the person record from the current step.
You need to get the opportunity from the process storage because the process an be started with and without context.
- Click Apply.
- Click (Edit step arguments).
- Save the step definition.
Step CreateY2
- Create a step called
CreateY2
allowing the user to create a new opportunity participant. - Select the action (
ExpandNew
) and define its input arguments:-
infoAreaID
:Y2
-
link
: the link to the person -
link2
: the link to the opportunity
Since
link
andlink2
come from the dispatching definition of the previous step, you only need to select "Input Message" as Source and select "as is" from the Value drop-down list. -
- Define the Dispatching:
- Enter the condition:
$.get('command')=='Save'
Saving the record navigates to the next step.
- Select "Step" as data provider (Source).
- Create the Next Step, see Step EvalY2Count.
- Enter the condition:
Step EvalY2Count
- Create a step called
EvalY2Count
to calculate the current number of opportunity participants. As soon as at least one participant is added, the user can exit the process. - Select
$nop
as Action Template:EvalY2Count
is an evaluation step executed in the background. For further details, see $nop. It just recalculates the current participant count and leads back to the Process Ask page which is updated with the result. - To get the current participants count you need to run a query. Define a custom
data provider
curY2
using the built-in external data providerExecuteQueryDataProvider
. For further details, see ExecuteQueryDataProvider.- Enter the
queryStatement
:select (Opportunity, FirstName, LastName) from (Y2)
- Enter the parent
link
for the query getting the opportunity record from the process storage:$.get('curY1Uid')
- Enter the
- You need to explicitly initialize this data provider: Add an input argument for
the
$nop
action that usescurY2
as source. You can enter any name as argument name (curY2Initialize
in this example). - To pass the current participants count (i.e. the number of result
rows) to the next step you need to define an output argument writing the result to
the process storage variable
curY2Count
: Definestep.get('curY2.$').getNumberOfRows()
as Value. This returns the number of rows in the current query result from data providercurY2
. For more functions, see ExecuteQueryDataProvider. - Define the Dispatching: This invisible evaluation step always returns to the Process Ask page, see Step ProcessAskY1.
Process Ask Configuration ProcessAskY1
The Process Ask configuration defines the items to be displayed on the Process Ask page
displayed by step ProcessAskY1
. For further details, see Step ProcessAskY1.
- Create a Process Ask configuration called
ProcessAskY1
. - Add the desired elements (Caption, Expand View, Text, Separators,
Buttons). For further details, see Process Ask Configuration.
You can pass most of the parameters as URL-parameters since they are defined as input arguments of
ProcessAsk
action in step Step ProcessAskY1.-
Expand View:
{expandName:'Y1.Process'}
. You do not need to specifyuid
here, since it is automatically passed from theProcessAsk
action. For further details, see Expand View. -
Linked Records: Specify a
TableCaptionName to determine from which info area
the linked records are read. Specify the link relation to be used
(
$Children
) under Parameters. For further details, see Linked Records. -
Text:
- The DisplayText uses the
Y2Count
argument: "You have {url:Y2Count} participant(s) linked to your opportunity". For further details, see Text. - The image (specified under Parameters) uses the
Y2State
(0 or more participants) argument:{image: 'CAT_ZF_
{url:Y2State}'}
(The images used are called
CAT_ZF_0
andCAT_ZF_1
.)
- The DisplayText uses the
-
Button: Here you define the buttons triggering the
events for the dispatching of step
ProcessAskY1
. For further details, see Button.The second button (Show Opportunity) is only displayed, if at least one opportunity participant has been added:
{url:
Y2Count}>0
. For further details, see If...End If.
-
Expand View:
Menu Action ID_NET_Process_NewOpportunityForCompany
- To call your process (without context) create an application menu action
ID_NET_Process_NewOpportunityForCompany
inID_NET_PROCESSES
(i.e. the Sales menu). For further details, see Configuring a Menu. - Select
Process
as Action Template. - Enter the name of the process as input argument
name
.
Context Menu Action A_StartProcessNewOpportunityForCompany
- To call your process (with context) create a context menu action
A_StartProcessNewOpportunityForCompany
inM_Opportunity
. - Select
Process
as Action Template. - Enter the name of the process as input argument
name
. - Define
uid
asRecord
(i.e. the opportunity record to start the process for). Definelink
asLinked
(i.e. the parent company of the opportunity).This writes these two records to the input message of the process.
If started from the context menu, the process automatically jumps to the
second phase because of the conditions you defined for that phase
(!!$.get('curY1Uid')
). For further details, see Phase AddY2.