You can use server-side jobs to have MDrivenServer select data and execute ViewModel actions without a logged-in user; this page is for developers designing automated or background work.
What server-side jobs do
A server-side job is a ViewModel configured for server-side execution. MDrivenServer runs it periodically: it evaluates the job's selection expression, loads the ViewModel for each selected object, executes the actions on the root ViewModel class, and saves resulting changes.
Use a job when work must happen even when no client is open, or when one server-side performer must handle work that should not be performed concurrently by multiple users.
Typical uses include:
- Moving an object from one state to another when it meets a condition.
- Assigning unique sequence numbers.
- Calling a remote system to update data.
- Sending email.
- Processing work requested through an async ticket.
For the detailed configuration procedure and server-side access setup, see Documentation:Serverside actions. For a guided periodic-action example, see Training:MDrivenServer periodic server-side actions.
How a job runs
A job has two parts:
| Part | Purpose | Example |
|---|---|---|
| Selection expression | Finds the objects that need work. | Select orders whose state is AssignNumber.
|
| Root ViewModel actions | Performs the work for each selected object. | Assign the next number, then change the order state to NumberAssigned.
|
For every object selected, MDrivenServer instantiates the associated ViewModel and executes the actions available on its root ViewModel class. Design the selection and the actions together: after successful processing, change the object so that it no longer matches the selection expression unless repeated processing is intended.
For example, a job that selects objects where SomeString has a particular value can run an action that appends a character to that value. Because the value no longer meets the selection condition, that object is not selected again by the same rule.
Choose the right pattern
Use the following guide before creating a job.
| Need | Recommended approach |
|---|---|
| Process objects that have entered a particular state | Create a periodic server-side job that selects the state and moves each object forward. |
| Ensure requests such as number assignment are handled by one server-side performer | Use a server-side job. Have the client set a state that the job selects. |
| Run work requested by a user without making the user wait for completion | Use the async-ticket pattern. MDrivenServer recognizes the pattern and creates the required server-side jobs. See Documentation:Server for the Async Ticket Management entry point. |
| Pass values that differ by environment, such as production versus non-production behavior | Use Server Wide Variables. |
| Send email from a Turnkey deployment | Configure the job and its server-side behavior, then use Turnkey email settings for the email configuration. |
Create a periodic job
- Create or identify a ViewModel that is rooted in the object you want to process.
- On the ViewModel root class, choose Edit criterias for server side execute. This enables the server-side editing area.
- Define the selection expression so it finds only objects that are ready to process.
- Add the root ViewModel actions that perform the work for one selected object.
- Ensure the action changes the processed object to a state that prevents accidental reprocessing, when that is the intended lifecycle.
- Upload or evolve the model to the server environment where the job will run.
- Test with a deliberately small set of matching objects, then inspect execution information and logs.
Keep each job focused. A selection expression should identify work that is ready now, and the actions should complete one coherent unit of work for each selected object.
Example: assign an order number
A multi-user client cannot safely assume that it alone will take the next number in a sequence. Instead, let the client request the work and let the server perform it.
- Let a user move an order to the
AssignNumberstate. - Configure a server-side job to select orders in that state.
- In the root ViewModel actions, assign the number and change the state to
NumberAssigned. - If the client needs to display the result while it waits, refresh only while the order remains in
AssignNumber.
This separates the user request from the serialized server-side operation. The complete training walkthrough is in Training:MDrivenServer periodic server-side actions.
Account for server-side access
A server-side ViewModel runs without a logged-in user. Do not configure its access rules only for interactive users, or MDrivenServer may be unable to open the ViewModel.
When you use access groups, use the server-side pre-EAL and OCL-based access setup described in Documentation:Serverside actions. A common arrangement is:
- An administrator access group for testing the ViewModel interactively.
- A separate server-side access group enabled while MDrivenServer runs the ViewModel.
- No access for other users.
You can set UIAllowed to false when a ViewModel must not be available from the user interface. This does not replace correctly configuring server-side access.
Use environment-specific values
Server Wide Variables let the same server-side ViewModel behave differently in different environments. Declare the variable on MDrivenServer, use the same name in the server-side ViewModel, and save the server value with Submit. The server-wide pre-EAL executes before the rest of the job actions.
For example, a job can use an environment value to avoid exporting data from a non-production environment, or to direct exports to a different external system.
The same page documents special variables for detecting restarts and skipping a query/job, including the job-specific vSkipQueryAndSkipJob_<ServerSideViewModelName> variable.
Design and operational guidance
- Make the selection expression narrow. It should select only objects that are ready for the current operation.
- Make the action idempotent where possible: a repeated attempt should not create an unintended duplicate effect.
- Move processed objects out of the selected state. This is the primary protection against processing the same object repeatedly.
- Keep remote calls and email work observable. If an external operation fails, retain enough model state to identify what needs retrying.
- Do not assume that access rules behave as they do for an interactive user; a server-side ViewModel has no logged-in user.
- When deploying multiple Turnkey or MDrivenServer instances, review additional considerations with load balancing Turnkey and MDrivenServer before relying on job behavior.
Diagnose a job that does not run as expected
Start with the job's selection and access rules.
- Verify that the OCL selection expression finds the objects you expect.
- If the log reports
Skipped <actionname> due to enable==false <Viewmodelname> touched 0 objects, check the job's disable or enable expression. - Check access groups affecting the ViewModel, including any default access group. Confirm that the server-side execution path enables the required group.
- Review the execution log and the WorkInfo view to see whether the job starts, how long it runs, and whether work overlaps with other activity.
- Add the supported error-handling ViewModel columns and action when you need errors retained in your model.
Debugging MDrivenServer Serverside actions describes the log views, WorkInfo timeline, API status information, and model-based error handling in detail.