Configuring the First Step

Configring most user task / human task steps in your workflow are easy - you pass the magic three parameters PROCESS_ID, SUBFLOW_ID, and STEP_KEY into your task when it launches, and tge task returns those same three parameters back to the Flows for APEX engine when the step completes. Then the workflow engine knows exactly which step you are completing - and all is good.

But… the very first step in your workflow is diffent IF you also create and start the workflow at the same time. Why is this the case? Well – if you start a workflow and complete the first step in the same database transaction, we don’t necessarily know which step you are completing as the new process could have multiple active steps, and we need some help from the application to know which step you are completing.

If that sounds confusing, let’s step back and explore a few issues - before bringing it all back together later to show you how t configure that first step.

Issue 1: Where does your process start?

Well, of course it starts at the Start Event ( ) – but did we model that correctly? When we add a Start Event to a BPMN model, we should name that with the state or condition that exists for the process to start. So in an expense reimbursement business process, what is the starting condition? It could be:

  • Expenses to Reimburse, or
  • Expense Claim Submitted

It may seem pedantic, but these are different – does the process include creating the claim (completing an expense report), or does that exist already and we just need to reimburse it?

If you have a model like this which has a first step of Claim Expenses , but your application is. structured so that your user completes a claim form in an APEX page, then clicks on a Claim Expenses button, which then creates and starts a Flows for APEX process instance, inserts the expense records in the database, and then does a complete step, it’s easy to get confused about what’s going on!

Issue 2: What Steps become Current when you start your process?

If your process Start Event is always followed by exactly one user task, then we know which activity we’re starting on.

But if your process diagram processes an **exclusive gateway** before getting to the first user task, we could have a choice of two or more steps. Even more complex, if it processes a **parallel gateway** or an **inclusive gateway**, there could be multi0ple active steps -- and we need to know which one we are processing. If the task, for example our expense claim form, was completed **before** the process instance was started, the application doesn't know which step it's processing. It doesn't have all three of the magic three parameters -- and so we will have to get those using a query before we can **complete** the first step. The app will know the `PROCESS_ID` - that will have been returned by the **create process instance**. It's a good idea to return `PROCESS_ID` into the `PROCESS_ID` application item. What about `SUBFLOW_ID` and `STEP_KEY`? If there are multiple steps, you can usually combine some knowledge. that you have as the process designer and application developer into a query on the `FLOW_SUBFLOWS_VW` view to select the activity that you want. Once you have all three parameters, we're good to do the **complete step**. And the **Flows for APEX - Manage Flow Instance Step** plugin that is used to specify the step declaratively allows you to define your query as the source of the parameters for the **complete step**. That might all seem complicated, but let's look at a worked example - and you should see how. these ideas come together to get the first step done. And, as we said at the beginning, it's only getting started with this first step that has this complexity. Subsequet steps asre very straightforward. ## Getting Practical So let's look at a worked example using our expense claim scenario... We'll show you two ways to model this process and build this application. ## Approach 1: Starting With a Claim in this approach, our business process starts with a completed expense claim. Our business process diagram would look something like this: We would implement the Expense Claim input as an APEX page. Page processing for this would: 1. Perform the page DML processing (insert / update the expense records), returning a `claim_id` usig the standard APEX DML process. 2. Create and Start a Flows for APEX process instance, setting the business reference `BUSINESS_REF` for the insance as the `claim_id`.