Panel Name fwAccessControl/fwAccessControl_Export.pnl
Introduction

Export Access Control data panel

This panel is used to export the Access Control data: domains, groups and users definitions. It is considered as a helper tool for developers who need to distribute certain elements of the access control data, namely the definition of domains and privileges, with their code.
The panel is presented in Figure 1.

Figure 1: The Export panel

Selecting the objects to export

The main part of the panel is made of two lists: the list on the left allows to select the domains, groups, or users to be added; the right list contains the objects that are chosen for export. A set of buttons between the two list allow to move the items between the lists, hence add or remove objects from the Selected Object list on the right. The objects on the right list will be exported when the OK button is pressed.

To add an object to a list of selected ones, choose the type of the object: "Domains", "Groups" or "Users" in the combo-box above the left list, then select the name(s) of the object (note that you may select multiple objects if you hold CTRL key while clicking on the items), then press the >. The objects will appear in the list on the right, and will be greyed-out in the list on the left.
To remove the objects from the right list, click on them and press the < button.
You may use the >> and << buttons to move all items between the lists;

Dependency resolving

The panel contains the mechanism which assures that the data being exported is coherent and complete. For every imported user it checks if all groups, to which the users belong, are also exported; for every exported group it checks if all domains in which the group has access rights are exported. This consistency checking is performed on the list of objects currently selected for export (present in the rightside list), when the OK button is pressed. If any of dependencies is unresolved, the Log Window with the list of dependencies is displayed, asking whether the objects which are needed to fulfill the dependencies should be added to selection; accepting this results in these objects being appended to the rightside list. Only if all dependencies are fulfilled, the actual export may go on.
The dependency checking (and resolving) mechanism may be disabled by unselecting the Enforce consistency checkbox. When the checkbox is off, the dependency checking mechanism will not be employed, and clicking the OK button will export the list of objects being currently on the rightside list.


Instructions
To package the definition of domain(s) into a component:
If you develop panels that makes use of Access Control,
  • Open this panel using the Export button in the Setup panel.
  • In the file-chooser, navigate to the directory where you want to place the exported file, and type in the name for the file. To make it compatible with the Framework Component Installation/Packager tool, you should put the file in the scripts directory of your project, and give it the name with the .postInstall extension.
  • In the export panel, select the domain(s) you need to export; use > button to put selected domains on the rightside list.
    We discourage exporting groups and users into a .postInstall file. It is the task of your system integrator to define groups and users, and grant the privileges, then distribute the users and groups definitions using the Access Control Server. However if you insist on exporting groups and users for the reasons of convenience of your coworkers, please make sure that dependencies are resolved.
  • Use the component packager tool to add the .postInstall file to your component; add the requirement on fwAccessControl 2.5.0 component.
    Alternatively, edit the component's XML file and add line such as: <postInstall>scripts/MyComponent/MyComponentAC.postInstall<postInstall> , and <required>fwAccessControl=2.5.0</required>
    Remember to include the .postInstall file in the list of files you distribute.
Restrictions
  • If called directly, the panel will not save the data to any file - it will return the lines of code as a return value (see the Return Values from panel section below.
    It is therefore recommended to use the Export button in the Setup panel, which actually displays the export panel, then saves the data to a file (the path and name of which may be selected); it also "enriches" the exported lines of code in such a way that the exported file is ready to be run in a CTRL Manager, or as a part of a postInstall script of the Framework Component Installation Tool.

Return Values from panel
The panel should be opened using functions from the ChildPanel...Returns(... , df,ds) family.
When the panel is closed the following values may be returned in the df and ds parameters:
Variable Value(s) Description
dyn_float parameter (df[])
df[1] 1 OK button was pressed and export operations were succesfull
df[1] 0 Cancel button was pressed or an error was encountered
dyn_string parameter (ds[])
ds[] contains the lines of the code (in PVSS scripting language), that may be embedded into a script, and used to import the access control data. The code defines the void postInstall_fwAccessControl(dyn_string &exceptionInfo) function.
Typically, the code has a form similar to presented in the following example:
void postInstall_fwAccessControl(dyn_string &exceptionInfo)
{
string acComponent="fwAccessControl";
string acVersion="2.5.0";
int acInstalled;
fwInstallation_componentInstalled(acComponent, acVersion, acInstalled);
if (!acInstalled) { makeDynString(exceptionInfo,"ERROR","Access Control component "+
		    acVersion+" not installed","");return;};

if (!dynlen(exceptionInfo)) fwAccessControl_checkAddDomain("MyDCS",
		 makeDynString("Monitor Me","Control","Debug Him","Modify"),
		 exceptionInfo,
		 "MyDCS controls",
		 "MyDCS control system");

if (!dynlen(exceptionInfo)) fwAccessControl_checkAddGroup("DCSOperators",
		 makeDynString("SYSTEM:Visualize","MyDCS:Monitor","MyDCS:Debug","MyDCS:Control"),
		 exceptionInfo,
		 "DCS Opeators",
		 "A group of DCS shift operators");

if (!dynlen(exceptionInfo)) fwAccessControl_checkAddUser("joe",
		 makeDynString("DCSOperators"),
		 exceptionInfo,
		 "Joe, the Operator",
		 "tel. XXXXX",
		 "xxxxxxxxxxx",
		 4096,
		 TRUE);

}

Back to the documentation of the fwAccessControl component.

Piotr Golonka, CERN IT/CO-BE