# Workflow Functions
“Workflow Functions” (workflow functions or functions) within the PMG platform are a method to leverage defined workflows in various ways.
Workflow functions may be used to:
Encapsulate logic into a new workflow action for use within the workflow designer
Expose workflow functionality as a callable API for third party systems
Leverage workflow logic to provide data to other areas of the PMG platform
Workflow functions are intended to return data “immediately”, and therefore, the workflows are expected to run their entire course without any actions entering a waiting state, such as human activities, or timers. Workflow functions may, however, call additional workflows in “Standard” mode, and those workflows are free to run the full range of actions, including actions which enter a waiting state. Note, the Set Parent Variable action is not valid in this called workflow context as the parent workflow is “instant” and will not wait on the called workflow.
# Workflow Function Management
Workflow functions are managed from the PMG Workflow Designer, from “Manage, Workflow Functions”.
The Workflow Function management screen lists all defined workflow functions and provides features to allow the administrator to quickly establish selected workflow logic as a function, usable in many ways.
# Endpoint Settings
Endpoint settings are managed from the “Endpoint Settings” link provided.
Options for Endpoint Settings are below.
Auth Token Lifetime (Seconds) – Defines the time in seconds for auth token lifetime validity when using auth token security
The authorize returns expiration in the result.
Access Origin – Allows for a comma separated list of allowed resource identifiers for Cross-Origin Resource Sharing (CORS), which is used to set the "Access-Control-Allow-Origin" header. If you are accessing the workflow function endpoints from JavaScript and that JavaScript is not hosted at the same URL as workflow functions you need to set this with the name of the originating server.
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin for more details.
Note: Specifying the 'magic' word "origin" will allow all, and is better than using *, as they are not quite the same.
Enable Service – Determines if the dedicated service will process API calls vs IIS
Base URIs – Assists the dedicated service binding process by identifying the names to bind. This should be blank if “Enable Service” is disabled.
# Workflow Function Properties
To create a new set of workflow function properties, select the "Add+" button from the Workflow Functions Management screen. If a workflow is already open in the designer, and no workflow function currently exists with the same name, that name will be used by default for a new set of workflow function properties. To edit an existing workflow function, select the function by name from the left panel of the list of defined functions.
A workflow function has the following properties.
# Name/Path
The name of the workflow is the distinct name used to reference the defined workflow action. When used as a workflow action, the action will appear in the Workflow Designer action palette under the "Functions" category. When referenced RESTfully, the workflow name is used as the path for the function in the Workflow API Endpoint for the given workflow. The name is also used as the name of the workflow action, or as a data source within the PMG platform.
Example paths for Action name usage and naming are below
MyDataFunction
MyDataFunction/customers
Workflow functions are matched when called based on the highest matching precision of the URL used.
# Description
The description for the workflow function provides lightweight documentation for the workflow function, shown at different points in the application to support subsequent usage of the function. The description is provided as the auto-generated documentation within the “Workflow API Endpoints” web management screen.
# Workflow
This is the workflow to use for the workflow function.
# Execution
This property indicates the execution mode to be used for the workflow function. The following modes are available. Please see "Execution Mode Considerations" for implementation considerations.
Run In Web Server / InProc
This mode indicates that the workflow is to be ran “in process” or "in memory" by the PMG application. The PMG Web Portal and the PMG Workflow API service may run workflows in this mode depending on configuration. When “In Process” is selected, the full definition of the workflow to be executed is transmitted, and potentially cached into memory of the calling process. In this mode, the workflow is “ran” fully in memory, with no commits back to the PMG application database. This mode allows for very fast and efficient execution of the defined workflow, and offers additional scaling design opportunities.
Considerations
Due to the execution mode, information conveyed about the workflow and some options will vary and are typically available after the process has executed completely.
“In Process” workflows should generally never “wait”, meaning, that the workflow is intended to run its full definition until completion.
These workflows are executed in a single thread, and are generally thread-safe within the internally defined execution paths. Only a single action within a defined workflow will be processed at any given moment, even if the workflow is defined with parallel execution. This thread-safe mode is not a limitation, however, and this information is provided to inform the reader for advanced troubleshooting or consideration.
Workflows ran in this manner require all network resources, dependency files, or otherwise that may be required within the executed process. Additionally, the workflow is executed from the context of the host process, i.e. the PMG Portal, or PMG Workflow API Service. Some legacy API technologies are constrained by this execution context, and are therefore not compatible with this mode, commonly due to some 'interactive user' requirement or some permission issue. See the addendum, “Known connector limitations” for additional information.
Typically all actions which are self-contained or require only web standard communications can be executed in this mode.
Engine, Not Logged
This runs the workflow "in process" from an available workflow engine.
Like “in process” execution mode, these workflows should have no actions which enter a waiting state, and the workflows should execute immediately in their entirety.
Performance-wise, this mode is like “in process” with the added cost of data transfer and network latency to the calling process.
Processes ran in this mode have the full workflow engine resources available, just as a “standard” workflow would. Therefore, this mode can offer a comparably fast execution alternative to “in process”, accommodating actions having some compatibility issues.
Engine, Logged
This mode is like standard workflow execution mode, except that the workflow is expected to run its full course and return immediately. What you get in return is, that since it runs on a real workflow engine (and not perhaps the web server where it called from at the end point) is that there might be things like installed libraries, firewall setups, and access to other systems that exit on the workflow engine machine but are not on the web servers.
# Execution Mode Considerations
Generally, "Engine, Not Logged" is recommended for a balance of workflow performance gains along with support of various workflow actions, typically integrations, which may run more readily from the workflow engine context. Below are more details and considerations about the available modes.
Both "InProc" and "Engine, not logged" will potentially relieve pressure from the application database, as the work is distributed and run in memory of the host process, without storing back to the database the execution details as the workflow is processed. Additionally, Engine, Not Logged (ENL) offers a set of benefits over InProc. ENL executed workflows run from the workflow engine process. This has certain benefits over InProc where your workflow would typically run from the web server (IIS).
One, in InProc mode, all the workflow will execute from within the web process. This means resources like CPU are being committed to that workflow execution which may impact end users who are accessing the platform from the web browser. To take this to an extreme, if a busy workflow runs for 5-10 seconds or longer to generate some complex data result, and more than one user is accessing this feature at a given time, then in this case, the web server is now processing that workflow, contenting for resources to respond to web requests. If this workflow instead runs from the workflow engine, then workflows may run a little slower, if at all, and end users of the web application are then unlikely to notice any performance differences or be impacted.
Two, with ENL, as workflows are ran from the workflow engine, you get all the benefits of not running inside of IIS while instead running from the workflow service. IIS can have unknown permissions limitations and restrictions which can keep many types of code from running as expected, for example, SAP code, an older technology, does not like to run from IIS. This is not limited to older technology though as even some new technology also does not work well or at all from within the IIS process.
Three, in addition to running from the workflow engine, you get the benefits of the workflow engine built in load balancing, and work will be automatically distributed to better use the available server resources.
While InProc can return individual workflow results slightly faster than ENL, typical end-to-end execution times of InProc vs ENL may only be several milliseconds. This difference is only true at low volume and you can anticipate workload continuing to be shared among the available workflow engines as load increases.
InProc is a valid execution mode, and you may, for very short running workflows, say 100-500ms be satisfied with this execution mode. However, performance could change quickly with high volume, or if the workflow requires more processing resources over time. Architecturally, if you plan ahead to use ENL, there's no particular downside.
It is good practice to start workflow development initially and perform workflow debugging using "Engine, Logged" as you will typically find more debugging features available. "Engine, Logged" mode will also help isolate issues related to timing or running from outside the the workflow engine.
# Output Type
Output type defines the mode by which the workflow is expected to return data. The different output types are valid for the different use modes of the defined function.
Variable
When the output type is “Variable” the workflow is expected to set one or more variables specified to contain the returned data. This output type is valid for “Workflow Actions” which can return any number of outputs to the calling workflow.
Single Variable Raw
The output type of string indicates that the workflow is expected to return a string as the result based on a specified variable's value.
String
The output type of string indicates that the workflow is expected to return a string as the result. See the PMG Platform actions “Set Output” and other related actions.
Table
The Table output indicates that the workflow will return a Data Table result, that is an array of data with columns or fields, and rows of values, with the actual data. See the PMG Platform actions “Add Table Output Row”, “Set Table Output” and other related actions.
**File **
The File output indicates that the workflow will return binary data, or a file.
# Run As User
When the workflow execution mode is set to “Engine-Logged”, the “Run As User” provides a default identity to execute workflows as.
# Input Variables
For different use cases of workflow functions, the “Input Variables” will expose the selected variables to be set by the caller.
# Output Variables
For different use cases of workflow functions, the “Output Variables” will expose the selected variables to be set by the caller as outputs of the workflow function.
# Endpoint Enabled
Establishes if the endpoint is enabled or disabled, determining if the workflow will be executed when called via the REST endpoint.
# Advanced
# Valid Values for Input Variables
Allows for providing valid values for one or more workflow variable inputs. For the published workflow action, the workflow action properties for this variable will be presented as a select list.
# URL Parameter Mapping
URL Parameter Mapping allows for workflow variable values to be parsed and set directly from the calling URL string. To define a mapping, replace the sections of the input URL with exact case matched variable names within the workflow and surround the name with curly brackets. For example, the below mapping
customers/{customerId}/accounts/{accountId}
defined for a workflow function named 'RestRequestDataTest' will parse the below example URL
RestRequestDataTest/customers/CustomerA/accounts/A101
setting customerId and accountId in the called workflow as 'CustomerA' and 'A101' respectively.
# Request Method
Provides an optional selection of an available workflow variable to store the REST request method used in the call
# Request Path
Provides an optional selection of an available workflow variable to store the REST request path used in the call
# Query String
Provides an optional selection of an available workflow variable to store the REST query string used in the call
# Allowed Methods
Provides a selection of one or more methods, e.g. GET, HEAD, PUT, etc, that will be accepted from REST call
# Request Headers
Provides an optional list of one or more request header mappings to map the named REST request header into a target workflow variable. For each entry, provide the case sensitive request header text along with the variable to store the submitted matching REST request header entry.
# Request Body
Provides an optional selection of an available workflow variable to store the REST request body used in the call
# Cache Duration
Cache Duration is an optional amount of time in seconds for which for REST calls providing the same inputs will receive a response from a cached copy vs from a newly executed workflow. This is useful under certain conditions, like high load, where requests are repeated often and it is not necessary to re-execute a workflow on each call to generate the return data.
The cache can be disabled by the client using the header in the request "Use-Function-Cache" with the value of "false".
The response header of "X-Function-Cached-Response" indicates if the reponse data is from a cache, as true or false.
# Response Headers
Provides an optional list of one or more REST response header mappings to map the named REST response headers from a selected workflow variable. For each entry, provide the case sensitive response header text along with the variable to use for the REST response value.
# MFA
Specifies if MFA is enabled or disabled for the REST call
# Logging
Specifies if logging of the workflow function is enabled or disabled
# Permission
One or more permissions for the workflow. Defines access restrictions for a workflow to be called as REST. More defails can be found under Permission section.
Permissions may be set as follows:
# UserId
Defines which users may access the workflow function as REST.
(*) asterisk – defines that the workflow function may be called by any user ID, or, a specific user ID may also be provided.
# API Key
The API key provides an alternate authentication method to access the workflow function as REST.
Note: To configure a fully anonymous API endpoint, set * for both UserId and for API Key.
# Expire Date Time
An optional datetime after which the workflow is no longer callable.
# File Upload
PMG Workflow Functions support File type variables for upload within the REST API. To upload a file to a workflow function, declare a file type variable and define a workflow function specifying the file variable as an input.
To test the file upload from the PMG web tools, use a valid file path on the server where the PMG engine is running.
For example:
Below is a curl example to send a file to a PMG workflow function.
curl --form MyFile=@C:\Temp\DeleteMe\xxxxx.zip --form SomeData=exampletext <http: localhost:81/wffn/functions/workflowfunctionfilevar?_authKey="c31e2416-1f47-3777-db0b-5c9df45b9414">
Below is an importable workflow example using the PMG REST action to upload a file.
<workflows>
<workflow collectionid="General" name="RESTFileUpload" versionnum="1" importtype="v8" wftype="service">
<notes></notes>
<actions>
<action left="360" top="60" width="60" height="60" givenname="Send File to WF FN" typename="GenericRestAction">
<description></description>
<properties>
<property typename="stringVarName" isoutput="false">
<valueexp><![CDATA[response]]></valueexp>
</property>
<property typename="ErrorOut" isoutput="false">
<valueexp><![CDATA[error]]></valueexp>
</property>
<property typename="datatypeToExpectCustom" isoutput="false">
<valueexp></valueexp>
</property>
<property typename="datatypeToExpect" isoutput="false">
<valueexp><![CDATA[Custom]]></valueexp>
</property>
<property typename="stringStatusName" isoutput="false">
<valueexp><![CDATA[status]]></valueexp>
</property>
<property typename="datatypeToPass" isoutput="false">
<valueexp><![CDATA[_multipart/form-data]]></valueexp>
</property>
<property typename="encoding" isoutput="false">
<valueexp><![CDATA[UTF8]]></valueexp>
</property>
<property typename="datatypeToPassCustom" isoutput="false">
<valueexp></valueexp>
</property>
<property typename="dataToPass" isoutput="false">
<valueexp></valueexp>
</property>
<property typename="timeout" isoutput="false">
<valueexp></valueexp>
</property>
<property typename="method" isoutput="false">
<valueexp><![CDATA[POST]]></valueexp>
</property>
<property typename="url" isoutput="false">
<valueexp><![CDATA[<root text="1" mode="text"><text lang="text">http://Computer:81/wffn/functions/WorkflowFunctionFileVar</text>
]]></valueexp>
</property>
<property typename="stringHeadVarName" isoutput="false">
<valueexp><![CDATA[headerdata]]></valueexp>
</property>
<property typename="authScenario" isoutput="false">
<valueexp><![CDATA[PMGNET_DOMAIN_JLORD]]></valueexp>
</property>
<property typename="formdata" isoutput="false">
<valueexp><![CDATA[<rows runtimeData=""><row><field name="Key">SomeData</field><field name="Value">C{{q_Text_Area}}</field></row><row><field name="Key">MyFile!</field><field name="Value">C{{q_Files}}</field></row>
]]></valueexp>
</property>
<property typename="headerParams" isoutput="false">
<valueexp><![CDATA[<rows runtimeData=""><row><field name="Key">Bobo</field><field name="Value">MyValue</field></row>
]]></valueexp>
</property>
<property typename="urlParams" isoutput="false">
<valueexp><![CDATA[<rows runtimeData=""><row><field name="Key">_authKey</field><field name="Value">zzz</field></row>
]]></valueexp>
</property>
</properties>
</action>
</actions>
<links>
<link name="c2" condition="Successful" source="Send File to WF FN" target="Send File To Form">
<link name="c1" condition="" source="Start" target="Send File to WF FN" prefdir="RL">
</links>
</workflow>
</workflows>
# Returning Files
Workflow APIs can return a file as well. To configure a workflow API to return a file, configure the following for the Workflow Function from the Edit Workflow Function screen
Output Type: File
Output Variables: select a file variable from the workflow which will contain the file to be returned
Response Headers:
content-type: ContentTypeHeader
cache-control: CacheControlHeader
Then, in the workflow, make sure to set the file variable using available workflow actions.
# Endpoint Permission
When setting API access permissions for a Workflow Function the permission usages are "Anonymous", "Basic Auth", "API Key", "Authorize Method", and "Cookie". Depending on your use case, or requirements if multiple modes are required, you may need to create separate API access endpoints to avoid logical conflicts in permissions.
# Anonymous Usage
To enable anonymous API access, both UserId and API Key should be set to "*"
# Basic Auth Usage
Basic Auth usage requires the username and password to be provided in the "Basic Auth" Authorization header in the request.
To enable basic authentication, do the following:
Set UserId as "user@domain.com": The user/password in the Basic Auth header will be authenticated and if it matches UserId here, the user is allowed. Optionally, use "*" as the UserId value which allows any authenticated user to access the API.
In the settings for this permissions row, leave "API Key" blank, as it is not used with basic auth.
In the request, send a normal "Basic Auth" Authorization header.
Notes:
If you set API Key and UserId to "*", it will be considered anonymous. Also, "Expire Date Time" and "MFA Token" cannot be used and are ignored.
If "Run As User" is set to "Authenticated User", the workflow will be ran as the authenticated API user.
# API Key Usage
Use this method when sharing an API Key with clients to access the endpoint.
To define and use an API Key for security, do the following:
Provide an "API Key" and do not use "*" as the key value
"MFA Token" is required if MFA is enabled. The token cannot contain ":"
Provide a valid "UserId" entry with one of the following:
UserId options Blank disables this API key "*" enables the key and the workflow will run as SYSTEM Provide a user ID (e.g. "user@domain.com") and with "Run As User" set to "Authenticated User", the workflow will run as that user Provide an Expire Date Time, or leave blank for no expiration.
Notes:
- For MFA, Authorization header must start with "Bearer "
- API/MFA tokens are not case sensitive
# Authorize Method
Use this method to obtain a token to use in subsequent requests.
To use the Authorize method, do the following:
Use the /authorize endpoint to obtain an AuthToken. See Workflow API Endpoints for the authorize endpoint
Send AuthToken in the Authorization Header, starting with "AuthToken "
Provide a valid "UserId" entry with one of the following:
UserId options "*" enables the AuthToken for all users Provide a specific user ID (e.g. "user@domain.com") to limit to a specific user. If run-as-user is "authenticated user" the workflow will run as that user, else it will run as system.
Notes:
- Authorization header should start with "AuthToken "
- The token will be valid for 30 days
- The AuthToken method is case sensitive
# Cookie Method (1)
Use this method if you want to make JavaScript calls to function endpoints from the same domain as the portal.
- Set system setting SEND_API_SESSION to true
- Set "Run As User" to "Authenticated User"
# Cookie Method (2)
Use this method if you want to make JavaScript calls to function endpoints from a different domain from the portal.
- Set system setting SEND_API_SESSION to true
- Set "Run As User" to "Authenticated User"
- Set "Access Origin" to "origin"
- Set system setting "SEND_P3P_HEADER" to "True"
# Testing Workflow Functions
The Workflow Functions Management screen provides a method to test defined workflow functions. For a given workflow function, the testing function allows the user to provide values for defined input variables. The workflow processing results will be opened in a newly displayed window, either as a full execution diagram for “Engine Logged” workflows, or as a detailed analysis of the workflow execution for the other execution modes.
Any output of the executed workflow will be indicated in the “Test Result” window.
# General Considerations for Workflow Functions
It is important to consider the execution modes and “scope” when designing for workflow functions, and how their execution mode relates to other called workflows. In particular, the execution time of the called workflow has the most implications or differences when compared to “standard” workflow execution mode. If workflow functions are intended to be used in a real-time interface, e.g. the PMG Portal, then the called API or the workflow actions should be expected to execute in very small timeframes. Otherwise, the user experience will suffer due to wait times. Built-in caching may be able to assist with slower performing APIs or generally to increase performance. In regard to execution modes of workflows called as an API, it can be important to consider some important differences. For example, “in process” or “not logged” workflows will be ran instantaneously. If that process invokes a call workflow action, it will not wait on the called workflow, and that called workflow will have some limitations in regards to what it might normally be able to do with its calling workflow. For example, the called workflow cannot use “Set Parent Variable” as there is no running/waiting workflow instance which could receive that update.
# Workflow Functions I/O
Workflow functions generally receive their input through variables declared in the start step of the workflow definition. Depending on usage, workflows may return data similarly through variables, or as a string of data or as a data table, using the provided actions which create the return data in the desired format.
# Workflow Functions MFA
Workflow Functions provide options to enable Multi-factor authentication (MFA). MFA values can be saved to a variable for further evaluation in workflow.
# Workflow function uses
# Workflow Actions
When a workflow function is defined to be used as a new workflow action, the variables which are declared as inputs and outputs will be available as action properties for the new action.
Defined workflow actions are then available from the designer actions palette.
# Workflow Action Outcomes
Workflows defined as Actions can return “outputs” or “paths” the same as other actions by using the “Set Workflow Output” action.
By default, Workflow Actions will return "Success" or "Error", where Success is any execution with unhandled action errors. Error will only be followed if some unhandled error occurs. To define different outcomes for the workflow actions to follow, define the outcomes as needed in the "Return Values" property for the workflow action, and use the "Set Workflow Output" action within the Workflow Action's workflow. The below simplified example declares that the WeatherAPI workflow action can return "No Weather" and then sets this output in the workflow action design, which can then be used in the calling workflow.
Defining the workflow action outcomes
Setting the workflow action outcome within the workflow action design
Using the outcome in the calling workflow
# Workflow Actions Palette
To make the Workflow Actions Palette available, it must be unhidden from the designer menu under “Manage”, “Actions”, Category “Functions” and select “Unhide”.
Workflow Actions provide a property to specify the execution mode of the workflow from the “Execution” property. Options are InProc, Engine Not Logged, and Engine Logged.
NOTE: If the execution mode property is not available for an existing Workflow Action, it may need to be resaved from the Workflow Functions management screen.
# Workflow API
Workflow functionality may be exposed to third party systems as RESTfully callable API. Additionally, the defined workflows are published with lightweight automatically generated usage documentation. Workflow APIs may be secured through a secret, or through user ID, leveraging the PMG platform’s configured authentication.
# OpenAPI support
Published workflows REST APIs can be accessed as an OpenAPI specification document at the URL server /spe/DesignerTools/OpenAPI This URL provides the JSON document which can be consumed by a Swagger UI, https://swagger.io/tools/swagger-ui/ and other supporting tools like Swagger Codegen https://swagger.io/tools/swagger-codegen/ and other development and documentation tools to display and interact with the APIs.
# Workflow API Endpoints Explorer
The Workflow API Endpoints explorer provides a user interface to allow end users to browse and execute REST callable workflow functions. The Explorer is accessible from the Workflow Functions Management screen from the “Workflow API Endpoints” link.
The interface provides auto-generated documentation for the defined endpoints and includes example input and output formats expected.
# Testing of endpoints
If the function is set with token based authentication, the token can be entered for the provided “Token” input, along with any other input variables given. To run the endpoint, click “Execute”. If the API is set with basic-authentication requirements for a specific user, then the user will see a browser challenge for basic-auth credentials.
# Postman support
Postman is a popular tool for testing and working with REST endpoints. Defined PMG Workflow Functions provide an export option which generates a Postman project file which can be loaded into Postman for testing.
# Data Workflows
Workflow functions can return data for various uses throughout the PMG platform. The “Data Workflow” actions provide options to return data as a table or a string. See the Workflow Actions section, “Data Workflows” for more information.
# NOTE: Workflow Functions - Connector considerations
The following connectors are known to exhibit issues with “In Process” execution.
SAP ECC, which requires the use of SAPNCO3 connectivity
Microsoft Office Automation, which requires interactive desktop user rights
PowerShell based actions
Processes requiring a local user account with “log in” rights
Azure, using Azure PowerShell interoperability
Remedy ITSM, using ARAPI
Any libraries requiring COM Interop. Due to known performance and memory leak issues related to COM Interop, any logic required to use interop should be fully isolated as a disposable process.
# Workflow Functions Execution Mode
Workflow Functions can be set to run either from IIS or from a Windows Service. IIS is the default mode. While generally fine, IIS may exhibit certain performance overhead constraints when using workflow functions, particularly when IIS recycles and incurs start up time overhead. To reduce or negate the IIS start up time response issue, Workflow Functions may alternatively be ran from a Windows Service. To enable Workflow Functions to run as a service, see the system setting, “ENABLE_WORKFLOW_FUNCTION_SERVICE”. When set to True, new options to configure the listening web service are made available. From the Workflow Designer, “Workflow Functions Manager”, access the “Endpoint Settings” option.
Access Origin: Allows for a comma separated list of allowed resource identifiers for Cross-Origin Resource Sharing (CORS)
Enable Service: A toggle for the system setting for the execution mode for Workflow Functions.
Base URIs: a list of URIs for which to bind the listening workflow functions when ran under the Windows Service
# Synchronous workflows
Synchronous workflows are a mode of execution of deployed workflows managed by the PMG Workflow engine. In this mode, workflows are immediately executed, and upon completion, will notify the calling application, providing data results as needed.
Synchronous workflows make available the capabilities of the workflow engine to all aspects of the PMG Platform, as well as to external applications, and offer various modes of operation and data exchange for varying use cases. As the workflows are executed synchronously, no actions which can go into a waiting state (human actions, wait for message, etc.) should be used directly. If any awaiting actions are needed, they should be executed separately by the call workflow action, and ran as a separate workflow instance, which would be executed by the PMG Workflow engine. It can be useful when considering usage options of synchronous workflows, to consider these workflows as “atomic functions” which are going to execute as a single process, and immediately provide some result.
# Synchronous workflow execution modes
# Run In Web Server
In this mode, workflows are executed in memory, in process of the calling application, and the PMG Workflow engine simply serves the workflow definition to the calling application. In this mode, the executed workflow does not persist its execution state to the database, providing substantial performance gains.
Benefits
This mode should be considered for usage where workflows may be called in high volume, or performance (time to execute and overhead) is a consideration. This mode provides a highly scalable workflow execution mode, as workflow processing is no longer managed within a fixed environment, and any number of additional servers may execute workflow processes in parallel. This mode is optimized for usage within the PMG Portal and Forms components, to provide scalability and performance. The PMG workflow engine is used only to deliver the defined workflow to be ran to the calling application. Then, the calling process, will then use PMG Workflow Libraries to execute the defined workflow locally. This provides workflow scale and speed, and provides benefits for end users using aspects of the PMG platform which involve human interaction, i.e. Portal, forms, reports, work items, etc.
Considerations
Workflows which are executed in this mode are fully disposed on completion. Workflows executed in this mode are ran from the calling application. This means that any workflow actions used will be ran from the environment and security context of the calling application. Many legacy actions have limiting factors for usage in these contexts, and may encounter execution issues under this context.
As the workflows are running from the calling application (web application), the workflow must have any required dependency libraries and network access available, similarly to requirements for executing the code from the PMG Workflow Engine.
To troubleshoot or diagnose workflows executed “InProc”, consider changing the mode to “EngineLogged” to leverage full workflow diagram execution analysis, with step details, logging, etc.
# Run in Workflow Engine – Not Logged
In this mode, workflows are executed in process, within the process of the PMG Workflow Engine. The executed workflow does not persist its execution state to the database, providing substantial performance gains.
Benefits
This mode should be considered when workflows may be called in high volume, or performance (time to execute and overhead) is a consideration. This mode provides a high performing and scalable workflow execution mode, as workflows are executed immediately, and ran to their completion in a single process.
As the workflows are running in the context of the workflow engine, typically more of the legacy integrations (connectors) will execute in this mode, while providing similar performance gains of “Run in Web Server”.
# Run in Workflow Engine - Logged
This mode runs workflows in the “Standard” mode, which is that the workflow is executed by the PMG Workflow Engine, and execution diagrams are generated for the workflows which run.
Benefits
This mode provides the most flexibility for development, troubleshooting, and diagnosis of workflow definitions intended to be ran synchronously. Workflows executed in this mode will run within the PMG Workflow Engine, and will have diagrams generated for each individual workflow execution state, which can then be used for detailed information about the executing workflow.
Considerations
This mode should be used typically only for development and troubleshooting synchronous workflows, as the workflow state is fully persisted to the database for each action executed within the workflow, and no prioritization is given to the workflow for execution. Also, as these workflows will typically be used in a high-volume use case, e.g. driving data for forms, reports, widgets, etc. there is a database and performance cost of storing the complete workflow context and its history as is the case for any workflow ran in full logging mode.
# Synchronous Workflow Usage
Synchronous workflows are available for multiple use cases, and based on need, various tools, special workflow actions, and administration interfaces are provided to streamline their setup and usage.
Synchronous workflows may be considered for nearly any case where specialized software development is required as an alternative.
# Post Logon processing
The PMG Platform provides the ability to hook into the logon process when users authenticate to the PMG Platform, typically through the PMG Portal or Work view. This hook provides flexibility to extend the user logon with additional specialized logic to perform various functions. Common examples are to add the user to custom groups based on specialized logic or real-time lookup to a third party system, or to redirect the user to a particular link, page or web function based on some condition such as a “First time logging in” event.
# Workflow as a PMG Provider (deprecated)
In older versions, workflows were callable as a data source by using an installed provider, SynchronousWorkflowRunner. This is deprecated and no longer needed, as data workflows are callable directly throughout the application.
# Workflow as a data source
Synchronous workflows may be used directly by PMG Forms to drive data to basic and rich form elements. This data can be used as any other data source within a form, to drive form field visibility, trigger other field values, or to be sent to the supporting workflow. To use a workflow as a data source, the workflow must be deployed with at least one “Set Synchronous Table Output” actions, or “Add Synchronous Table Output Row” actions. Once deployed, the workflows will be visible from the form edit mode for standard fields which support data sources. Deployed workflows will be selectable in the “Data Source” property for a database driven field, under the “Data Workflows” section.
Once a data workflow is selected, all the variables declared in the selected workflow will be displayed as optional inputs from the data source dialog.
Data workflows may also be invoked from certain Rich Form Elements by selecting the Data Workflow as a source. To provide the “Query” to the data workflow, create a JSON document with each desired input variable to set, with its given value as below.
{
"variables": {
"InputData": "My Value"
}
}
Data Workflows are also available for use within reports as a data source, from the Report Editor, individual report properties, “Advanced”, “Query” screen.
# Synchronous Workflow Actions
# Set String Output
The Set String Output action allows a data workflow to return a custom string result to the caller. This string can be a simple value such as “Yes” or “No”, or may contain rich data as JSON format, XML, or any other needed format.
# Set Table Output
The Set Table Output action allows the workflow to convert a rich data document in either JSON or XML format into a “pivoted” tabular response as columns and rows. This action provides the following properties
Data Variable
Specifies which workflow data variable contains the source data to be converted into a table.
# Data Root
Specifies the parent node XPATH, or leave blank for JSON sources.
# Columns
Defines the tabular format to be returned. The screen allows for any number of entries for each needed table “Column Name” and the “Path” for the source of the row for the data to return. For XML documents, the path is either simply the name of the node, or the XPATH to the data.
An example screen is below.
If the source document is JSON format, then similarly, the “Path” is the name of the JSON field, or is the JSON Path using dotted notation to the inner values, such as “spec.brand”. If the JSON property has spaces in its name, the path can use the following example syntax.
$.['I have spaces']