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

  1. Create a new process called NewOpportunityForCompany.

    Since your process contains phases you do not need to specify an Initial Step.

  2. The Header drop-down list lists all info area-independent special headers.
  3. For the process metrics define a custom Data Provider curTexts loading the text group containing the multilingual texts used in the process.
    1. Enter a Name.
    2. Define an Action using the built-in external data provider UsingDataProvider. For further details, see UsingDataProvider.

    3. Enter the name of the desired text group as argument texts.
    4. Click Apply.
  4. 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: The uid 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. Since curY2Count is accessed at different points of the process, it must be defined in the process storage.
    • repMetric: $t('TXT_Process_TextGroup_0') gets text number 0 of text group Process_TextGroup. Syntax,. For further details, see Referencing Texts in JavaScript. The text group has been loaded by the custom Data Provider curTexts.
    • curRepName: The name of the current rep. Available functions for identifying the current rep. For further details, see u8.session.identity.
  5. 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):

  1. Under Process Phases click (Add).

  2. Enter a Phase Name.
  3. Enter a Phase Label. This is displayed on the phase arrow.
  4. 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.

  5. 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 phase AddY2.

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

  7. Click Apply.
  8. 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 step EvalY2Count.

Step SelectFIForY1

  1. Create a step called SelectFIForY1 allowing the user to select (or create) a company for which to create the opportunity.

  2. Define the action: In this case a sub-step is called (ExecuteSelectRecordSubStep) that uses the existing step SelectCompany->Return.

    ExecuteSelectRecordSubStep returns the uid of the selected record. For further details, see ExecuteSelectRecordSubStep.

  3. To pass the uid of the selected FI record to the next step you need to define an output argument for the step: The uid is written to the process storage variable curFIUid. 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.
  4. 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

  1. Create a step called CreateY1 allowing the user to create a new opportunity.

  2. 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')
  3. 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:
    1. Enter a Name.
    2. Define an Action using the built-in external data provider ReadRecordDataProvider. For further details, see ReadRecordDataProvider.

    3. Get the uid of the record to read from the process storage: $.get('curFIUid')
    4. Enter the IDs or XML names of the fields to be read.
    5. Click Apply.
  4. Define the input arguments defaultValues and defaultFields. For further details, see defaultFields/defaultValues.
    • Get defaultValues from the custom data provider curFIRep: $.get('RepID')
    • Enter the IDs or XML names of the target fields as defaultFields
  5. To pass the uid of the created Y1 record to the next step you need to define an output argument for the step: The uid is written to the process storage variable curY1Uid. 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.
  6. Define the Dispatching:
    1. Enter the condition: $.get('command')=='Save'

      Saving the record navigates to the next step.

    2. Select "Step" as data provider (Source).
    3. Create the Next Step, see Step ProcessAskY1.

Step ProcessAskY1

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

  2. Select the action (ProcessAsk) and define its input arguments:

    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.
  3. 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 provide uid as output argument you need to get the uid for ViewRecord->Exit from the process storage:

Step SelectKPForY2

  1. Create a step called SelectKPForY2 allowing the user to select (or create) a person to be added as opportunity participant.

  2. Define the action: Analogous to SelectFIForY1 a sub-step is called (ExecuteSelectRecordSubStep) that uses the existing step SelectPerson->Return. It returns the uid of the selected person record.
  3. Define the Dispatching: Since there is only one possible next step (creating the opportunity participant), enter "true".
  4. Create the next step, see Step CreateY2. Pass the uid of the selected person and the opportunity (parent of opportunity participant) to CreateY2:
    1. 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.

    2. Click Apply.
  5. Save the step definition.

Step CreateY2

  1. Create a step called CreateY2 allowing the user to create a new opportunity participant.

  2. 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 and link2 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.

  3. Define the Dispatching:
    1. Enter the condition: $.get('command')=='Save'

      Saving the record navigates to the next step.

    2. Select "Step" as data provider (Source).
    3. Create the Next Step, see Step EvalY2Count.

Step EvalY2Count

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

  2. 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.
  3. To get the current participants count you need to run a query. Define a custom data provider curY2 using the built-in external data provider ExecuteQueryDataProvider. 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')
  4. You need to explicitly initialize this data provider: Add an input argument for the $nop action that uses curY2 as source. You can enter any name as argument name (curY2Initialize in this example).
  5. 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: Define step.get('curY2.$').getNumberOfRows() as Value. This returns the number of rows in the current query result from data provider curY2. For more functions, see ExecuteQueryDataProvider.
  6. 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.

  1. Create a Process Ask configuration called ProcessAskY1.

  2. 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 specify uid here, since it is automatically passed from the ProcessAsk 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 and CAT_ZF_1.)

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

Menu Action ID_NET_Process_NewOpportunityForCompany

  1. To call your process (without context) create an application menu action ID_NET_Process_NewOpportunityForCompany in ID_NET_PROCESSES (i.e. the Sales menu). For further details, see Configuring a Menu.

  2. Select Process as Action Template.
  3. Enter the name of the process as input argument name.

Context Menu Action A_StartProcessNewOpportunityForCompany

  1. To call your process (with context) create a context menu action A_StartProcessNewOpportunityForCompany in M_Opportunity.

  2. Select Process as Action Template.
  3. Enter the name of the process as input argument name.
  4. Define uid as Record (i.e. the opportunity record to start the process for). Define link as Linked (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.