VA FileMan 22.2 Developer's Guide HTML Manual Banner
VA Office of Information and Technology (OIT) Banner

Contents: Main Section See Also: User Manual Advanced User Manual

Data Access Control (DAC) API

$$CANDO^DIAC1(): Policy Evaluation

Once a policy has been created and tested, it is ready to be used by the new VA FileMan Web service or within an application’s own code. The $$CANDO^DIAC1 API evaluates a policy to determine if the action being attempted is permitted.

If a matching entry exists in the APPLICATION ACTION (#1.61) file for the requested action and specified file or sub-file, its policy is evaluated to determine the user’s authorization to access the file and/or record. Policy rules are evaluated in sequence, and processing continues until the stop criteria for the policy is met.

Format
    $$CANDO^DIAC1(file,iens,action[,user][,.value][,.fields][,msg_root][,err_root])
Input Parameters
file:

(Required) A VistA file number or sub-file number.
iens:

(Required/Optional) Standard IENS string indicating internal entry numbers. It is required if evaluating an action on an existing record.
action:

(Required) The API name of the action to be taken on the record; the file and action parameters should identify an entry in the APPLICATION ACTION (#1.61) file.
user:

(Optional) Pointer to the NEW PERSON (#200) file; defaults to the current value of DUZ if not defined.
value(name):

(Optional) Array of additional attribute values to use when evaluating policies, passed by reference in the form:

    VALUE(“name”) = “value”

The name-value pairs could match target attributes in the policy for supplementing the results of the ATTRIBUTE FUNCTION, or simply be additional values used by other functions or messages.

NOTE: The ATTRIBUTE FUNCTION (#.04) field of the POLICY (#1.6) file points to the TYPE (#.03) field of the POLICY (#1.62) file.

.fields:

(Optional) Local variable that receives output from the call:

  • If the AVAILABLE FIELDS (#5) field of the POLICY (1.6) file have been defined for the application action and its policy returns a permit result, that field string is be returned.

  • If AVAILABLE FIELDS (#5) field of the POLICY (1.6) file have been defined for the policy or rule that determined the result, that string takes precedence over the action’s and be returned instead.

  • The ADDITIONAL FIELDS (#5.1) field of the POLICY (1.6) file can also be returned here, as an array of the same name subscripted by the file or sub-file number.

NOTE: The .fields parameter is passed by reference, which is indicated by the dot (.) in front of the name in the parameter list. Every parameter is passed using variables, but if it’s passed by reference then whatever happens to the variable inside the call also happens to the variable in the calling program. (That is not the case with normal parameter passing, without the leading dot.) The fields variable is KILLed at the beginning of each call.
msg_root:

(Optional) Closed root into which any relevant advice messages is returned. If this parameter is not passed, the array is put into nodes descendant from ^TMP(“DIMSG”,$J).
err_root:

(Optional) Closed root into which the error messages are returned. If this parameter is not passed, the array is put into nodes descendant from ^TMP(“DIERR”,$J).
Output

This Boolean extrinsic function returns the following:

Advice messages can be returned for either a Permit or Deny result. Available Fields are only returned on a Permit.

Examples
Example 1

To check the current user’s authorization to view a chemistry result using our sample Lab policy, a simple call could be made to the API, as shown below:

>S OK=$$CANDO^DIAC1(63.04,“7019779.8679,12345,”,“read”) W !,OK
1
Example 2

A different user may not be permitted to view the result, and the message array can show why, as shown below:

>S OK=$$CANDO^DIAC1(63.04,“7019779.8679,12345,”,“read”,1000406,,,“ZZMSG”)
>W OK,! ZW ZZMSG
0
ZZMSG(1)=“FMUSER,ONE is not authorized to view preliminary results.”
ZZMSG(2)=“Please contact Lab staff.”
Example 3

An incomplete call to the API returns an error, as shown below:

>S OK=$$CANDO^DIAC1(63.04,“7019779.8679,12345,”,,,,,“ZZMSG”,“ZZERR”)
>W OK,! ZW ZZERR
-1
ZZERR(1)=“The input parameter that identifies the ACTION is missing or invalid.”

 

VA (Internet) / VA (Intranet) / OIT / EPMO / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: January 19, 2018

If you have questions, need more information, or are having accessibility problems with this Web site, please contact us by E-Mail: Webmasters