OverviewCopy link to clipboard
This page provides guidance on how to use the Start Process Smart Service to initiate processes in your process models, interfaces, and web APIs. By default, processes initiated using this smart service are run asynchronously, meaning that the current process flow will continue without waiting for these processes to complete. You can also run processes synchronously if you need to wait for data from the other process.
Learn more about other ways to start a process, and how they compare to this smart service, here.
Permissions neededCopy link to clipboard
The behavior of the node depends on the permissions of the user running the smart service, both when starting the process and when the process is complete. The following table shows the result of running the smart service at different permission levels.
Permission Level | Result of Executing Smart Service |
---|---|
Deny or Not in Role Map | The smart service errors, generating an error message for the process administrators and preventing the process from being started. |
Initiator | The process is started, but when starting the process synchronously, only the process instance ID or instance UUID (processInfo.pp.id, processInfo.pp.instanceUuid ) is populated. All other processInfo values will be null, and the PV domain (processInfo.pv ) will be empty. |
Viewer and Above | The process is started, and all process model properties, process instance properties, and process variable values are populated in the processInfo output value. |
Note: The Modify Process Security smart service can change a user's permissions for a specific process. When starting a process synchronously, Appian checks the user's permission when the process completes and returns the appropriate data for that level.
PropertiesCopy link to clipboard
-
Category: Process Management
-
Icon:
-
Assignment Options: Unattended/Attended - Note: When this smart service is attended, the form that the user sees is the form configured on the node, not the start form for the specified process model.
Configuration optionsCopy link to clipboard
This section contains tab configuration details specific to this smart service. For more information about common configurations see the Process Node Properties page.
Setup tabCopy link to clipboard
This tab makes it simple to pick a process model, choose how it should run, and configure the inputs and outputs so data flows correctly.
Start a process asynchronouslyCopy link to clipboard
The smart service can start other processes to run in the background.
To start a process asynchronously:
- On the Configure Start Process dialog, click the Setup tab.
- For Process Model, select the process model you want to start. You can select a model by name, or you can use an expression to select a process model (using a constant referencing the process model or the process model's ID).
- For How Should This Process Run?, select Asynchronously.
- For Inputs, do one of the following:
- If you selected the process model by name, the parameters will appear automatically, letting you set the values using the dropdowns.
- If you selected the process model using an expression, click Add Parameter, then enter the parameter name and add a value.
- Click Edit as Expression and use a map or dictionary to define the parameters and values.
- Click OK to close the dialog.
Start a process synchronouslyCopy link to clipboard
The smart service can wait for the other process to complete, and you can then assign any returned data to a process variable for use later in the process.
To start a process synchronously:
- On the Configure Start Process dialog, click the Setup tab.
- For Process Model, select the process model you want to start. You can select a model by name, or you can use an expression to select a process model (using a constant referencing the process model or the process model's ID).
- For How Should This Process Run?, select Synchronously.
- For Inputs, do one of the following:
- If you selected the process model by name, the parameters will appear automatically, letting you set the values using the dropdowns.
- If you selected the process model using an expression, click Add Parameter, then enter the parameter name and add a value.
- Click Edit as Expression and use a map or dictionary to define the parameters and values.
- For Outputs, do the following:
- Click Add Save Target.
- For Save Target, select a process variable to contain the output.
- For Value, select the ProcessInfo property that you want to store in the save target.
- Click OK to close the dialog.
Usage considerationsCopy link to clipboard
Starting multiple processes at onceCopy link to clipboard
You can use the Start Process smart service to start multiple processes at the same. The method for starting multiple processes differs depending on whether autoscale is enabled:
- If the process model does not have autoscale enabled: Use the Multiple Node Instances (MNI) option on the Start Process smart service.
- If the process model has autoscale enabled: Build a looping flow to start multiple asynchronous processes with the Start Process smart service.
Process depth protectionsCopy link to clipboard
Each time you start another process with the smart service, Appian increments a counter that tracks the depth of nested processes associated with the first process. This counter stops a recursive or deeply nested process model from starting more processes than the system can handle. Autoscaled processes have a maximum depth of 1000 processes; processes without autoscale have a maximum depth of 100.
Importantly, there is only one counter that tracks the current process depth and checks it as each process is started; you may encounter the limit at an unexpected point if you mix processes with and without autoscale. For example, say you start an autoscaled process that recursively starts 250 more autoscaled processes. If the 250th process needs to start the next process without autoscale, this would result in an error because 251 is greater than the 100 limit.
Run processes in parallelCopy link to clipboard
When you need groups of work to happen at once, you can use the smart service to launch multiple, parallel processes. While you can draw parallel flows in a process model, the nodes on these branches will run in sequence.
There are three configurations where processes started synchronously run in parallel:
- An autoscaled process starts a process without autoscale enabled.
- A process without autoscale enabled starts an autoscaled process.
- A process without autoscale enabled starts a process without autoscale.
All processes started asynchronously run in parallel.
Using activity chainingCopy link to clipboard
This smart service acts on activity chaining in specific ways depending on whether you are starting an asynchronous or synchronous process.
Chaining through an asynchronous Start Process node causes the original process to continue without interruption. No connection is maintained with the process that is started by the smart service, and any activity chaining is separate from the original process.
Chaining through a synchronous Start Process node means the original process will wait for other process to complete before continuing. Any activity chaining in the started process is not connected to the original process, so a broken chain will not return process variables to the original process. If a chained flow encounters an attended activity, the activity will be assigned to the user that the Start Process smart service was run as, but it will not open the associated form.
a!startProcess()Copy link to clipboard
The Start Process smart service is available as an expression function that can be executed inside a saveInto on a Interface Component or as part of a Web API. To learn more about using this function in interfaces, see Starting Processes From an Interface.
SyntaxCopy link to clipboard
a!startProcess( processModel, processParameters, isSynchronous, onSuccess, onError, onIncomplete )
ParametersCopy link to clipboard
Keyword | Type | Description |
---|---|---|
|
Process Model |
The process model to start, identified by a constant or the process model's ID. |
|
Any Type |
A dictionary or map of the parameters and values to set at the start of the process. |
|
Boolean |
When true, |
|
Any Type |
A list of |
|
Any Type |
A list of |
|
Any Type |
A list of |
Set the process parametersCopy link to clipboard
The Process Parameters property is a map or dictionary where the keys are process parameter names and the values are parameter values. If any required parameters are missing or a parameter is not valid for the selected process model, the process will not start.
For example, if you have a process model that controls an employee review cycle, it might have a required parameter named employeeId
and optional parameters named deadline
and reasonCode
.
To successfully start this process, the Process Parameters input would look like one of the following:
1
2
3
a!map(
employeeId: 12345,
)
Copy
1
2
3
4
a!map(
employeeId: 12345,
deadline: today()+30,
)
Copy
1
2
3
4
5
a!map(
employeeId: 12345,
deadline: today()+30,
reasonCode: "ANNUAL"
)
Copy
In the following examples, the process would not start. For the first two cases, the reason is that the required process model parameter, employeeId
, was not provided. For the third case the reason is that an entry in the Process Parameters input, supervisorId
, did not match any of the parameters of the process model.
1
2
a!map(
)
Copy
1
2
3
a!map(
deadline: today()+30,
)
Copy
1
2
3
4
a!map(
employeeId: 12345,
supervisorId: 6789
)
Copy
Node outputsCopy link to clipboard
Output | Data Type | Description |
---|---|---|
Process Info | ProcessInfo | Contains information about the process that was started, its model, and the values of its process variables |
Handle a!startProcess() resultsCopy link to clipboard
When configuring a!startProcess()
, you should set each result parameter (onSuccess, onError, and onIncomplete) so the user starting the process knows what happened and if they need to take further action.
The onSuccess parameter is evaluated at different times depending on whether the process is run asynchronously or synchronously and whether autoscale is enabled.
- When a process without autoscale enabled runs asynchronously, onSuccess is evaluated when the request to start the process is successfully sent.
- When an autoscaled process runs asynchronously, onSuccess is evaluated when the process is added to the queue; some time may pass before the process actually starts.
- When a process runs synchronously (with or without autoscale enabled), onSuccess is not evaluated until the process is complete.
The onError parameter is evaluated if the selected process can't be started, regardless of whether it is run asynchronously or synchronously. It will not evaluate if a node in the started process cannot complete because of errors.
The onIncomplete parameter is only evaluated if a process runs synchronously and any of the following occur:
- The process is canceled.
- The process cannot complete because of errors.
- The process does not finish within 30 seconds.
- The initiator does not have permission to view the process when it completes.
For example, when you create a web API with the Start Process template, these parameters are set up with appropriate HTTP responses (including status codes and data). You can then customize each a!httpResponse()
to suit your application.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
a!startProcess(
processModel: cons!ID_WRITE_LOG,
/* A dictionary or map of parameters passed to the process model */
processParameters: a!fromJson(http!request.body),
isSynchronous: false(),
/* This expression will run when the process is started (when run asynchronously) or completed (when run synchronously) */
! onSuccess: a!httpResponse(
statusCode: 200,
headers: {
a!httpHeader(
name: "Content-Type",
value: "application/json"
)
},
body: if(
a!isNotNullOrEmpty(fv!processInfo),
a!toJson(fv!processInfo),
null()
)
),
/* This expression will run if the process fails to start */
! onError: a!httpResponse(
statusCode: 500,
headers: {
a!httpHeader(
name: "Content-Type",
value: "application/json"
)
},
body: a!toJson(
{
error: "There was an error starting the process"
}
)
),
/* If the process is started synchronously, this expression will run if the process does not complete in 30 seconds */
! onIncomplete: a!httpResponse(
statusCode: 504,
headers: {
a!httpHeader(
name: "Content-Type",
value: "application/json"
)
},
body: a!toJson(fv!processInfo)
)
)
Copy
Use a!startProcess() with web APIsCopy link to clipboard
When designing a web API that will call a!startProcess()
with isSynchronous set to true, you should consider that Appian has a default pool of 200 concurrent HTTP requests available. This pool is shared by web APIs and end users of your applications, so a web API serving many requests at once can negatively impact site performance for end users.
ProcessInfo propertiesCopy link to clipboard
When you start a process synchronously, data is returned in the ProcessInfo activity class parameter (or fv!ProcessInfo
for a!startProcess()
).
These and the following properties can be mapped to an output of the smart service node or the onSuccess, onError, or onIncomplete parameter of a!startProcess()
.
The following table lists the properties available based on the state of the process.
Property | onSuccess | onIncomplete (process started) | onIncomplete (process queued or deleted) | Notes |
---|---|---|---|---|
pv | ✓ | Empty list | Empty list | |
pp!id | ✓ | ✓ | Null | Available when autoscale is not enabled |
pp!instanceUuid | ✓ | ✓ | ✓ | Available when autoscale is enabled |
pp!name | ✓ | ✓ | Null | |
pp!priority | ✓ | ✓ | Null | |
pp!initiator | ✓ | ✓ | Null | |
pp!designer | ✓ | ✓ | Null | |
pp!startTime | ✓ | ✓ | Null | |
pp!endTime | ✓ | Null | Null | |
pp!deadline | ✓ | ✓ | Null | |
pp!timeZone | ✓ | ✓ | Null | |
pp!execId | ✓ | ✓ | Null | Available when autoscale is not enabled |
pp!errorCount | ✓ | ✓ | 0 when queued, null when deleted | |
pm!id | ✓ | ✓ | ✓ | |
pm!name | ✓ | ✓ | ✓ | |
pm!description | ✓ | ✓ | ✓ | |
pm!version | ✓ | ✓ | ✓ | |
pm!creator | ✓ | ✓ | ✓ | |
pm!timeZone | ✓ | ✓ | ✓ | |
pm!uuid | ✓ | ✓ | ✓ |
Feature compatibilityCopy link to clipboard
The table below lists this smart service function's compatibility with various features in Appian.
Feature | Compatibility | Note |
---|---|---|
Portals | Compatible | |
Offline Mobile | Incompatible | |
Sync-Time Custom Record Fields | Incompatible | |
Real-Time Custom Record Fields | Incompatible | Custom record fields that evaluate in real time must be configured using one or more Custom Field functions. |
Process Reports | Incompatible | Cannot be used to configure a process report. |
Process Events | Incompatible | Cannot be used to configure a process event node, such as a start event or timer event. |
Process Autoscaling | Compatible |
Old versionsCopy link to clipboard
There are older versions of this smart service. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.
Old Versions | Reason for Update |
---|---|
a!startProcess_24r3 | This function was evolved to be compatible with autoscale and to allow processes to start synchronously. |
To use the latest version of the smart service node:
- Drag in a new Start Process Smart Service node from the palette, and place it on the same connector as the current node.
- Configure the new node with settings matching your current, older node.
- Delete the old Start Process Smart Service node.
To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.