system.mes.signature.authorization.queueAuthRequest()

Sepasoft MES Module Suite

system.mes.signature.authorization.queueAuthRequest()

This function is the foundational step of the signature workflow. Its strategic purpose is to define and register a new authorization request within the system. Here, you configure the entire process, including who is required to sign and what logic should execute for every possible outcome: a successful approval, an explicit rejection, or a failed login attempt.

Adds a new request to have one or more users sign in. When all users have signed in an action will be performed.

Scope:Gateway, including Perspective component scripts, gateway events, and tag events, when the Perspective module is installed. It is not available in the Designer Script Console or in Vision clients.

Keyword arguments use approve, reject, and error. The names below match the callback functions in the example.

Parameter

Type

Purpose & Role

signatureTemplate

MESSignatureTemplate

Core Requirement: Defines the specific users and/or roles required to approve the request. This object forms the fundamental authorization rule for the workflow.

onApprove

PyFunction

Success callback. Runs only when every required user has approved.

Available in 3.81.13 SP5 and 4.83.3 SP5: the function may accept one argument, an AuthRequestResult containing every user who approved and when. A function with no parameters is still called with no arguments.

onReject

PyFunction

Rejection callback. Runs if any required user rejects the request. Available in

3.81.13 SP5 and 4.83.3 SP5: the function may accept one argument, an AuthRequestResult containing any earlier approvals followed by the rejection.

onError

PyFunction

Error callback. Runs when a login fails, times out, or is cancelled. Available in

3.81.13 SP5 and 4.83.3 SP5: the function may accept one argument, an AuthRequestResult containing the failed attempt and the reason. The request stays pending and can be signed again.

description String Optional description for the authorization request.

requestName

String

Optional title for the authorization request.

Available in MES 3.81.12 SP2 and MES 4.83.1 SP2 and later

Returns

This function returns a List of UUID objects. Each UUID is a globally unique identifier that represents a single signature request for one of the users required by the template. These UUIDs are essential, as they are used to invoke the correct challenge with the triggerAuthRequest() function. In a typical implementation, this list of UUIDs must be persisted or passed to the client session so that it is available when the user is ready to trigger the authentication challenge.

List<UUID> - A list of UUID objects that represent the requests for the different users that need to sign in.

Callback data

Starting in 3.81.13 SP5 and 4.83.3 SP5, onApprove, onReject, and onError can take one argument. def onApprove(data): receives an AuthRequestResult. A parameter with a default (def onApprove(data=None):) or *args also receives that object. A function with no parameters is called with no arguments. A function that requires two or more parameters is not supported.

In a task-routed system the callbacks run on the runtime gateway. Timestamps are when that gateway received each signature. Queued requests and their callbacks are held in gateway memory and are cleared by a gateway restart.

AuthRequestResult

Method	Returns	Description
`getRequestName()`	String	Request name passed to `queueAuthRequest`.
`getDescription()`	String	Description passed to `queueAuthRequest`, or `None`.
`getSignatureTemplateName()`	String	Signature template used for the request.
`isApproved()`	Boolean	`True` only when every required user approved.
`getLastUser()`	String	User whose signature completed, rejected, or failed the request. `None` if that login did not succeed.
`getUsers()`	List of String	User name of every signature, in signing order. A user appears once for each signature.
`getSignatures()`	List of AuthSignature	Every signature, in signing order, including a rejection.
`getApprovals()`	List of AuthSignature	Approving signatures only.
`getRejections()`	List of AuthSignature	Rejecting signatures only.
`getErrorMessage()`	String	On `onError`, why the attempt failed. `None` for `onApprove` and `onReject`.

onApprove receives one signature per required approval. onReject receives earlier approvals, then the rejecting signature. onError receives only the failed attempt. getErrorMessage() is "The authentication challenge was cancelled.", "The authentication challenge timed out.", or "The signing user does not satisfy the signature template."

AuthSignature

Method	Returns	Description
`getUserName()`	String	User who signed. `None` if the login timed out or was cancelled.
`getTimestamp()`	Date	When the gateway received the signature.
`isApproved()`	Boolean	`True` when the user approved. `False` when the user rejected.
`isAuthenticated()`	Boolean	`False` when the login did not succeed.
`getRoles()`	List of String	Roles of the signing user.
`getSecurityZones()`	List of String	Security zones the user signed from.

Methods:

system.mes.signature.authorization.queueAuthRequest(signatureTemplate, onApprove)
system.mes.signature.authorization.queueAuthRequest(signatureTemplate, description, onApprove)
system.mes.signature.authorization.queueAuthRequest(signatureTemplate, onApprove, onReject)
system.mes.signature.authorization.queueAuthRequest(signatureTemplate, description, onApprove, onReject)
system.mes.signature.authorization.queueAuthRequest(signatureTemplate, onApprove, onReject, onError)
system.mes.signature.authorization.queueAuthRequest(signatureTemplate, description, onApprove, onReject, onError)
system.mes.signature.authorization.queueAuthRequest(signatureTemplate, requestName, description, onApprove, onReject, onError)

Script Example

Copy Code

Python

def onApprove(data):
	log = system.util.getLogger("Approve")
	for sig in data.getApprovals():
		log.info("%s approved by %s at %s" % (data.getRequestName(), sig.getUserName(), sig.getTimestamp()))

def onReject(data):
	log = system.util.getLogger("Reject")
	log.warn("%s rejected by %s" % (data.getRequestName(), data.getLastUser()))

def onError(data):
	log = system.util.getLogger("Error")
	log.warn("Signature failed for %s: %s" % (data.getLastUser(), data.getErrorMessage()))

obj = system.mes.loadMESObject("admin", "SignatureTemplate")
requestUuids = system.mes.signature.authorization.queueAuthRequest(obj, "Admin Approval", "Approve admin change", onApprove, onReject, onError)

This script logs who approved and when, who rejected, or why a login failed. It loads the Signature Template named "admin" and stores the returned UUIDs in requestUuids. Those UUIDs are passed to triggerAuthRequest() to open the challenge. A callback with no arguments, such as def onApprove():, still runs and is called without data.

Sepasoft MES Module Suite