You can customize your trellispark UX to enable your users to invoke custom workflow in two ways:
- Commands – selectable from the Instance toolbar to cause workflow to be performed
- Events – triggered from the Instance toolbar to cause an instance state transition
Events are significantly more complex than Commands from a developer perspective. Events are used to explicitly change the state of the currently selected Instance (and possibly its children). As part of the event processing:
- Workflow can be triggered before the state is changed
- Assuming that the before change workflow is successful, the Instance state is then changed, and possibly cascaded into children of the currently selected instance
- Assuming that the state changes are successful, workflow can be triggered after the state has changed
Users generally do not discriminate between Commands and Events, so both are grouped together in the drop-down component in the Instance toolbar.
See here to create and configure a command.
See here to create and configure an event.
REST API Core – Execute Command
This is the primary target of any Command or Event requested by a user interacting with the trellispark UX. It provides three endpoints:
- ExecuteCommandData – can be called by trellispark UX or your custom workflow
- ExecuteLocalCommandData – should only be called by default trellispark UX
- ExecuteQueuedCommand – should only be called by default trellispark UX
GreatIdeaz has exposed all these endpoints for customers who want to customize the default trellispark UX to meet their specific business needs. If you want to redefine the default trellispark UX you can download the following source code projects:
- UX-WASM-Components – Controls the overall look and feel of the trellispark UX
- UX-WASM-SA – Controls how users are signed into the trellispark UX
For detailed instructions on how to customize the trellispark UX see this document.
Depending upon how you customize the trellispark UX, you may need to be able to make calls on all endpoints.
GreatIdeaz recommends that you only use the ExecuteCommandData to maximize compatibility and take advantage of user security access checks.
Endpoint: ExecuteCommandData
This endpoint is called by the trellispark UX when it needs to request processing of a custom Command or Event that has been created in the Data Model. Wizards also call this endpoint to make API calls when Previous/Next buttons are selected.
The payload passed by the request is defined as ExecuteCommandInformation with the following input values:
- SessionGUID: The current SessionGUID of the signed in user.
- UserGUID: The UserGUID of the signed in user.
- CurrentInstanceGUID: The InstanceGUID of the record that the user is currently looking at.
- TargetInstanceGUID: The InstanceGUID of the record containing additional information to be applied during the request. This will be an empty InstanceGUID until the Wizard functionality has been implemented.
- CommandGUID: The InstanceGUID of the Command or Event that has initiated the request.
- CommandTarget: This value is only specified when an API call is being made from a Wizard. It contains the URL of the API to be called.
- CommandName: This value is only specified when an API call is being made from a Wizard. It contains the name of the command to be executed at the endpoint.
The following values are returned:
- UserMessage: Any message from the workflow to the user regarding the request that isn’t an error.
- ErrorMessage: An empty string if the request was processed successfully, otherwise a string that describes the error.
Endpoint: ExecuteLocalCommandData.
This endpoint is called by the trellispark UX components when they need to interact directly with the Data Model.
Only trellispark UX component local commands can be processed by this endpoint. You should not attempt to call this directly without first contacting GreatIdeaz for support.
The payload passed by the request is defined as ExecuteLocalCommandInformation with the following input values:
- SessionGUID: The current SessionGUID of the signed in user.
- UserGUID: The UserGUID of the signed in user.
- CurrentInstanceGUID: The InstanceGUID of the record that the user is currently looking at.
- TargetInstanceGUID: The InstanceGUID of the record containing additional information to be applied during the request. This will be an empty InstanceGUID until the Wizard functionality has been implemented.
- CommandName: The name of the local command that has been requested.
- StringValue: An optional string value that is used to provide additional context to the request
The following values are returned:
- UserMessage: Any message from the workflow to the user regarding the request that isn’t an error.
- ErrorMessage: An empty string if the request was processed successfully, otherwise a string that describes the error.
Endpoint: ExecuteQueuedCommand
This endpoint is called by the trellispark Generic Service to process asynchronous requests from the Queued Commands.
Only trellispark UX component local commands can be processed by this endpoint. You should not attempt to call this directly without first contacting GreatIdeaz for support.
The payload passed by the request is defined as RESTAPICommandInformation with the following input values:
- SessionGUID: The current SessionGUID of the signed in user.
- UserGUID: The UserGUID of the signed in user.
- CurrentInstanceGUID: The InstanceGUID of the record that the user is currently looking at.
- TargetInstanceGUID: The InstanceGUID of the record containing additional information to be applied during the request. This will be an empty InstanceGUID until the Wizard functionality has been implemented.
- CommandName: The name of the local command that has been requested.
The following values are returned:
- UserMessage: Any message from the workflow to the user regarding the request that isn’t an error.
- ErrorMessage: An empty string if the request was processed successfully, otherwise a string that describes the error.
Queued Commands
Not all REST API Commands are going to execute quickly.
The trellispark UX provides an option to indicate that certain commands need to be queued for execution instead of being processed immediately. This is called Asynchronous processing where the actual execution of the workflow takes place in the background whilst the user continues working on something else. By default, all workflow is assumed to be executed Synchronously (whilst the user waits).
Any Command REST API workflow can be tagged as being Async (the default is Sync).
When executing Event based workflow:
- The Before the state change REST API calls are always Synchronous
- The After the state change REST API calls default to Synchronous but can be marked as Asynchronous
The database maintains a QueuedCommand table that holds a list of commands that have been queued but not yet processed. Once a command has been processed, it is transferred into the QueuedCommand_History table if successful, or QueueCommand_Error table if it fails.
Generic Service
The trellispark Generic Service is a Microsoft Windows Service that is used to process Queued Commands in the background to free up users working on other tasks.
You can deploy as many copies of the Generic Service as you wish, and they are configured in your Workspace. Each Generic Service will need to be configured with a connection to the REST API and Workspace GUID.
Start by registering the Generic Service name in the Workspace form.
You can then define any required custom Command Queues in your Workspace form. Each custom Command Queue is then associated to a named Generic Service.
When you indicate that one of your UX Commands or Events needs to be Asynchronous, you will associate it with a named Command Queue.
As the Generic Service starts, it uses its REST API to determine which Command Queues it is to process using the configured Workspace GUID. It then enters a polled loop reading and executing any workflow added to the designated Command Queues.
Your custom REST API
This is a custom REST API created by you!
Its purpose is to process custom commands and events that are triggered within your workflows. You may choose to implement several distinct REST APIs to handle different types of commands and events.
Each of your custom REST APIs may implement one or more endpoints. Each endpoint may process one or more distinct named commands. This gives you maximum flexibility in determining how to partition your custom workflow code.
You link a custom REST API Endpoint using a Workspace configuration parameter using a Key/Value pair.
For example: Key = “MyCustomCode” maps to Value = “HTTPS://MyRestAPI.com/MyCommand”
When you define a Command or Event in the Data Model you specify the Key (MyCustomCode) as the Command Target.
When the user triggers the Command or Event, the trellispark REST API Core will look for a matching value in the configuration parameters defined in same workspace as the User. It will then use that matching value to call your custom REST API. This gives you maximum flexibility to configure a common command target across multiple environments (e.g. DEV, QA, Production) or workspaces.
NOTE that you don’t have to worry about whether your commands are to be executed Synchronously or Asynchronously in your REST API. You can always assume that the command is to be executed immediately by the time it hits your REST API. The background asynchronous execution thread is handled within the core trellispark framework.
Example Video
Endpoint: MyCommand
This endpoint is called in two ways:
- By user’s interacting with the trellispark UX and invoking custom Commands and Events created in your Data Model. The trellispark UX initially sends the request to the trellispark REST API Core for preliminary processing and validation. It can then either be queued for later execution or forwarded directly to your Custom REST API.
- By processing in your own custom REST APIs or services.
The payload passed by the request is defined as RESTAPICommandInformation with the following input values:
- SessionGUID: The current SessionGUID of the signed in user.
- UserGUID: The UserGUID of the signed in user.
- CurrentInstanceGUID: The InstanceGUID of the record that the user is currently looking at.
- TargetInstanceGUID: The InstanceGUID of the record containing additional information to be applied during the request. This will be an empty InstanceGUID until the Wizard functionality has been implemented.
- CommandName: The name of the local command that has been requested.
The following values are returned:
- UserMessage: Any message to the user regarding the request that isn’t an error.
- ErrorMessage: An empty string if the request was processed successfully, otherwise a string that describes the error.
Recommended Template
GreatIdeaz has included a recommended Visual Studio template for your custom REST API. The solution has two projects:
- REST API – Contains the endpoint controls and underlying logic for your custom workflow
- Test Logic – Contains the unit tests for the code that implements your logic.
GreatIdeaz recommends that you structure your REST API project into the following folders:
- Types – Contains any internal types used within your code.
- Logic – Contains any classes used to execute your logic.
- Controllers – Contains any endpoint controllers used to expose your logic.
To expose an endpoint called “Example”, GreatIdeaz recommends that you create an “ExampleController” derived from ControllerBase. This should only contain the minimum code required to:
- Accept and validate the format of the incoming JSON
- Connect to the database using the appsettings.json connection string
- Call an “ExampleCommand” class to process the request
- Return an appropriate response to the caller
The “ExampleCommand” class should expose an “ExecuteCommand” function that simply contains a switch statement that uses the “CommandName” to route the request to an appropriate function for processing.
This approach effectively:
- Makes your controllers simple unchanging wrappers that only need to be tested rarely using tools such as Postman
- Isolates all your actual workflow code into a set of classes that can then easily be invoked by unit test classes in the Test Logic project.
GreatIdeaz recommends that you create a Unit Test class for each of your Logic “ExampleCommand” classes with test cases for each of your named commands.
