Generic Job Parameters

Besides the input parameters defined by each job itself, the server kernel evaluates a number of parameters that can be passed with any job call — independently of the executing engine. This page documents these parameters centrally; the procedure pages of the individual jobs do not list them but refer here instead.

These parameters are recognizable by their triple-dollar notation ($$$Name$$$).

1. Switching the User Context for Job Calls

A server job can be executed in a different user context. For this purpose one of the following parameters is added to the job call:

Name Description

$$$SwitchContextUserGUID$$$

GUID of the user on whose behalf the job is to be executed.

$$$SwitchContextUserID$$$

ID of the user on whose behalf the job is to be executed. In enaio® 12.0 without effect — see Effectiveness of the Three Variants.

$$$SwitchContextUserName$$$

Name of the user on whose behalf the job is to be executed.

The three parameters are alternatives — the user is addressed either by GUID, ID or name. In enaio® 12.0, however, only the GUID and the name variant actually take effect (see Effectiveness of the Three Variants).

For jobs that evaluate the rights system, the permission check is performed for the specified user. Further jobs that are executed server-side as a consequence of the call — for instance an internal call of std.IndexDataChanged to create a history entry on DMS objects — then also run on behalf of the specified user.

The executing (logged-in) user requires the system role 72 (Server: Switch job context, internally R_SRV_SWITCH_CONTEXT). If it is missing, the call is rejected with the error code -1042218022 ("The system role R_SRV_SWITCH_CONTEXT is not present.").

The system roles assigned to the calling user can be determined with mng.GetUserRoles; an overview of all roles is available under System Roles.

If the addressed user cannot be assumed, the call is rejected with the error code -1043332467 — regardless of the job called and regardless of the cause (see Context Switch Errors).

The same role is also required by krn.CheckUserAccount — there without a context switch, solely to call the job.

A typical use case is an integration that is logged in under a technical service user but has to perform operations on behalf of the business user acting — so that user’s permissions apply and the history entry names them as the originator.

For the XML jobs of the DMS engine there is additionally the job-specific input parameter JobUserGUID (see The JobUserGUID Parameter), which is only permitted for server-side calls from other jobs.

1.1. Effectiveness of the Three Variants

In enaio® 12.0 only $$$SwitchContextUserName$$$ and $$$SwitchContextUserGUID$$$ switch the user context.

$$$SwitchContextUserID$$$ remains without effect: the job continues to run unchanged in the context of the logged-in user — without an error code and without a warning. This was tested as an INT and as a STRING parameter, with a valid as well as a made-up user ID and in several spellings (verified).

An integration that impersonates via the numeric user ID therefore silently continues to run with the permissions of the technical user. Use $$$SwitchContextUserGUID$$$ or $$$SwitchContextUserName$$$ for the context switch instead.

1.2. Context Switch Errors

If the context switch fails, the job call is rejected with the error code -1043332467 (0xC1D0028D). This code is purely a collective code: it is identical for all causes and only states that the context switch was not possible.

The cause is carried by the error stack of the response. It distinguishes five states of the target user — unknown or deleted, manually locked, locked by failed logins, expired and not yet valid; the corresponding codes are listed under Cause Codes in the Error Stack.

Anyone evaluating only the return value cannot distinguish a blocked target user from a deleted one. The error stack additionally contains entries without diagnostic value that are to be skipped — see Entries Without Diagnostic Value.

The user attributes mentioned can be checked in advance with mng.GetUserAttributes or mng.GetUserList.

never_expire does not override validto. An account with an expired validto and never_expire set still fails with -1042218315 — the flag only affects the password, not the validity of the account (verified).

The error is not job-specific: the same context switch fails identically with mng.GetUserRoles, mng.GetUserList and krn.GetServerInfo (verified). The context switch is performed before the actual job; the job in which the error shows up is therefore merely the first call after the switch.

1.3. States That Do Not Prevent the Context Switch

The following states of the target user switch the context regularly (verified):

  • The target user has no system role at all. A subsequent mng.GetUserRoles then returns an empty Result.

  • A forced password change is set for the target user (changepwd).

  • The target user has a validity window that includes the current point in time.

  • The target user has never logged in.