AURORA REST-Server Overview and Methods

General overview

This is the AURORA REST-server which serves requests and responses to and from the AURORA database and system.

For more information and in order to understand the entity tree of AURORA and how the various parts interact, please read the "AURORA Systems Overview"-document.

The AURORA REST-server is as the name suggests based upon the REST principles. However, it does not use various HTTP-methods based on what is being asked (such as "GET", "DELETE", "MOVE" etc.). Instead the method is implemented as a name directly under the server root, such as eg.:

/getTree

All HTTP-requests to the server must be sent as HTTP POST-requests. All requests are only served over HTTPS/SSL.

All method names starts with a verb describing what one wishes to do, eg.: get, delete, move, list, check and so on and so forth. Then that is followed by the entity type, such as eg.: Computer, Group, Dataset and so on and so forth (the subject). A few methods will not be associated with any entity types and as such will not have this as the second part of the method name (such as getTree). The last part of the method name will be the object of the verb (ie. what to get, delete, move and so on). Sometimes this will be the entity type as well, such as with the method-name: moveComputer.

The naming scheme of the methods also starts with a lower case letter and all subsequent words have an uppercase letter, eg: moveComputer, checkTemplateCompliance, listComputerFolder and so on and so forth.

In the same manner the AURORA REST-server has standardized its input and output parameters and return data based upon the method-name and some selected names. In most cases a parameter like "id" means the "id" of the subject/ object of the method when used as input. Eg. moveComputer takes "id" as parameter of the computer that one wants to move, checkTemplateCompliance takes "id" as the entity to check the template compliance for and getComputerMetadata takes "id" as the computer to get the metadata of (and so on and so forth). Another input parameter that is common in many instances is "parent" and is usually used to signify the group entity that is the parent of the entity in question. This is eg. used with moveComputer, moveGroup etc.

When it comes to output/result from the various methods, the result always comes in the structure named after the object of the request. So for example, getComputerMetadata will return the metadata in a sub-hash that is called "metadata". In the method enumTemplates the templates will be returned in a sub-hash called "templates".

All method requests to the AURORA REST-server uses JSON as encoding and HTTP POST as the HTTP-method.

All requests to the REST-server needs to contain authentication information, since all calls needs to be authenticated. Even so, the server optimizes its mode of operation and one can choose to connect to it by setting the keepalive-flag, so that each subsequent call uses the same established connection. However, no session data is kept and it is still required to authenticate for each call.

The authentication parameters are: authtype and authstr. The first authtype sets the authentication type to use. AURORA supports plugin classes for authentication and are also supplied with its own native AuroraID authentication type as well as OAuth-based authentication (SSO) called OAuthAccessToken. So if one wants to authenticate with the native AuroraID authentication, one sets authtype to "AuroraID" (the name is case sensitive, so be careful to get it right). The other parameter authstr sets the corresponding authentication string that matches the chosen authtype. Usually all authstr parameters will contain an email and then some sort of cookie/string or password. In the case of AuroraID the format of the authstr is as follows:

email,password

or eg.:

myname@mydomain.org,ThisIsMySecretPassword1234

In addition to the authstr and authtype parameters, each REST-server method has its own requirements which can be perused in this very document.

So, eg. for the call moveComputer, one would send a json string which looks like this:

{ "authtype":"AuroraID","authstr":"myname@mydomain.org,ThisIsMySecretPassword1234","id":314,"parent":413 }

In addition to these parameter requirements for REST-server methods, it might also be some permission requirements that the user has to fulfill in order to be allowed to successfully run it. These requirements will also be outlined the documentation of the method.

The REST-server will after all method calls issue a response. This response is also in JSON and is a HASH-structure which looks like this:

"received": STRING # unix datetime (UTC) with hires microseconds for when the request was received by the REST-server
"delivered": STRING # unix datetime (UTC) with hires microseconds for when the request reponse was sent by the REST-server
"err": INTEGER # 0 for no error, 1 for error.
"errstr": STRING # the failure reason upon an error, blank if no error.

The key-values will always be there in all method responses. In addition to these "global" response values, the various REST-methods will add additional key->values and sub-keys or hashes. These additional responses are documented in the REST-server method description itself.

The time format that are mentioned in the "received" and "delivered" response-values are unix datetime in high resolution format. The time is in UTC without any locales. This means that they come out like (string of float):

12345678.54321

where the hires part is after the dot "." in microseconds.

Some methods will even return sub-hashes. Eg. the getAggregatedTemplate-method will give you the mentioned global values and in addition a sub-hash called "template" (after the object of the method, the subject being the system or entity tree):

{"delivered":1593585453.44301,"received":1593585453.39645,"errstr":"","err":0,"template":{"system.user.username":{"comment":"This is the users email address","max":"1","flags":["MANDATORY","NONOVERRIDE"],"min":"1","regex":"[a-zA-Z]{1}[a-zA-Z0-9\\.\\!\\#$\\%\\%\\&\\'\\*\\+\\-\\/\\=\\?\\^\\_\\`\\{\\|\\}\\~\\@]+","default":null},"system.user.fullname":{"default":null,"regex":"[^\\000-\\037\\177]+","min":"1","max":"1","flags":["MANDATORY","NONOVERRIDE"],"comment":"This is the users full name. Accepts all non-special characters"}}}

Calling the REST-server

One can use many different libraries or software to connect to the AURORA REST-server as long as they support REST-type servers (basically HTTP). It is also possible to do REST-server calls by using the curl-command in linux like so:

curl -v -k -d '{"authtype":"AuroraID","authstr":"myname@mydomain.org,ThisIsMySecretPassword1234","id":314,"type":"COMPUTER"}' -H "Content-Type: application/json; charset=utf-8" https://localhost:1000/getAggregatedTemplate

Alternately if you are not comfortable with saving your AURORA authentication details in the history through the the command line, you can put the JSON structure inside a file instead:

curl -v -k -d @myjsonfilename -H "Content-Type: application/json; charset=utf-8" https://localhost:1000/getAggregatedTemplate

Permissions

The AURORA system has a rich system of permissions and all the various permissions can be set in the entire tree, but only on GROUP-, DATASET- and TEMPLATE entities. All permissions set will be inherited down the tree if not denied on the way down, which in essence means that only GROUP-permissions are inherited since the other entity types always resides at branch ends of the tree.

AURORA enforces a permissions scheme where the right to perform a method depends on the users permissions on the entity being manipulated. The permission must either reside on the entity itself or come down through inheritance. Note, however, that in most cases the system will allow the operation if the user in question has the correct permission on the parent of the entity being manipulated (also through inheritance on the parent). The reason for this is to avoid a scenario where denied permissions will lock users from manipulating or seeing entities.

Furthermore, the AURORA-system enforces the following rule when it comes to setting permissions: the user is only allowed to set/give away permissions that he himself has on the entity in question. This is to avoid security defects where having the right to set permissions gives you the option to elevate your own set of permissions, thereby achieving godhood (well, at least in that small part of the hood).

All permissions to and from the AURORA REST-server is specified in textual/string format. All permissions start with the entity type name, such as DATASET, TEMPLATE, GROUP and so on. Examples of permission names are:

DATASET_CREATE
DATASET_MOVE
GROUP_CREATE
GROUP_CHANGE

and so and so forth. All permission names are also uppercase, but the methods are case-insensitive when it comes to specifying the permission name. The permission name might not have a uniform meaning between methods as some methods might sometimes use the permission to signify certain permission variants relevant to that method. This is not the default use and meaning of the permissions, but if such cases exist, they will be documented in the method in question.

So, eg. the permission DATASET_CREATE obviously means that one has the permission to create a dataset on whatever group that one has this permission on. However, this permission is also used by the getTree() REST-method to signify that the user is not allowed to list or view (see that it exists) that dataset if he only has this permission on it. This touches upon the implicit permissions one has through having certain other permissions. In this example, one has the permission to view or list a dataset (not read its data or metadata) when one has any other DATASET-permission, except DATASET_CREATE.

Also, upon creating a dataset, the AURORA-system will assign all dataset permissions to the creating user on the dataset being created, with the exception of DATASET_DELETE, DATASET_MOVE and DATASET_EXTEND_UNLIMITED. This mechanism is to underline the fact that it is the parental group that owns the dataset and therefore manages both its location (move) as well as its state (delete). The DATASET_EXTEND_UNLIMITED is an admin-type permission that allows the holder to extend the expire-date unlimited beyond any expire-policy in the entity tree.

SQLStruct

When doing more sophisticated database operations in the AURORA REST-server it utilizes a structure called SQLStruct (for more technical details see the documentation of the SQLStruct-module). This structure makes it possible to define more refined SQL search parameters without actually writing SQL and are used by eg. the getDatasets()-method. The SQLStruct structure can either be a HASH or an ARRAY, while some methods might enforce one or the other (getDatasets()-method requires the main structure to be an ARRAY as in the example below).

The SQLStruct might look like this:

SQLStruct = ( 'OR', # First ARRAY element is ALWAYS the logical operator (LOP) of the ARRAY.
            { 'Creator' => 'Bård', # second ARRAY element is a HASH with key "Creator"
              'Created' => { '>' => '1990', '<' => '2000' }  # next HASH key is "Created" pointing to a sub-hash comparing years with LOP "AND".
            },        
            { 'Creator' => 'Jan Frode*', # third ARRAY element is a HASH with key "Creator" equals a name and then a wildcard
            },
            { 'Religion' => { '!' => "NULL", '-' => "NULL" } # fourth ARRAY element  is a HASH with a key "Religion" pointing to a sub-hash with a nonsensical comparison, of which nonsense religion sometimes mimicks.
            },
            '1', # fifth ARRAY element is just the value 1 (which will evaluate to true)
            [ 'not',   # the sixth ARRAY element is last and contains an sub-ARRAY, which again has a sub-HASH and so on.
              { 'Group' => 'Whatever',
              },
             '11'
            ],
            )

As you can see, both ARRAYS, HASHES and STRINGS are allowed within the structure itself. In the example above Perl notation has been used. "()" is an ARRAY, "{}" is a HASH, "[]" is a ARRAY-reference. "=>" is a value assignment for a key in a HASH.

SQLStruct has the following rule about the difference between an ARRAY and a HASH:

HASHES are used with various comparative operators (COP). The key or sub-key can be used to define the following valid COPs:

">"    # greater than
"<"    # lesser than
"<>"   # not equal to
"="    # equal to
">="   # greater than or equal
"<="   # lesser than or equal
"!"    # is not
"-"    # not
"&"    # bitwise and
"|"    # bitwise or
"^"    # bitwise xor

If the key is not a COP it must be a key-name that one wants to compare to a value in the following hash assignment:

KEYNAME => VALUE  # the value can contain wildcards

Values that the COPs are used with can contain wildcards in the form of "*". If one wishes to use "*" as a value in and of itself, the value must be escaped.

GENERAL METHODS

ackNotification()

Acknowledges a notice from a Notification.

Accepts the following parameters:

This methods requires no user permissions except being able to login to the AURORA REST-server.

Returns no special feedback upon success.

enumEntityTypes()

Enumerates all entity types in the database.

No input is accepted.

Upon success return the following HASH:

types = (
           ENTITYTYPEa => STRING # ID to textual name
           ENTITYTYPEb => STRING
           .
           .
           ENTITYTYPEz => STRING
        )

ENTITYTYPEa and so on are the entitytype ID and the STRING is the textual name of the entitytype type.

enumPermTypes()

Enumerates all permission types in the database.

No input is accepted.

Upon success return the following ARRAY:

types = ["PERMISSIONa","PERMISSION_b" ... "PERMISSIONz"]

PERMISSIONa and so on are the textual string name of the permission type.

getEntities()

Search for and retrieve entity(ies) matching name and type.

Accepted input parameters are:

Upon success this method returns the following structures:

entities => (
              entityID1 => {
                             name => STRING,  # textual name of entity
                             type => STRING,  # textual entity type
                             parent => INTEGER, # entity parent id
                             parentname => INTEGER, # entity textual parent name
                           }
              .
              .
              entityIDn => { ... }
           )
matches => INTEGER # number of matches found of given name-parameter

getHostSSHKeys()

Gets a hosts public SSH Keys through ssh-keyscan.

Input parameters:

Upon success returns the following structure:

sshkeys => (
   TYPE1 => PUBLIC KEY,
   .
   .
   TYPEn => PUBLIC KEY,
)

TYPE is the key type (ssh-rsa, ssh-dsa etc.). PUBLIC KEY is the actual key itself.

getMetadata()

Gets the general, open metadata of an entity.

Input parameters:

Upon success return the following structure:

(
   metadata => (
      NAMESPACE1 = STRING,
      .
      .
      NAMESPACEn = STRING,
   )
)

Where NAMESPACE is the name of a specific metadata value of the entity. It will only return metadata for an entity that is deemed open and public.

getName()

Gets the name of an entity.

Input parameters:

Upon success return the following value:

name => STRING # the textual display name of the entity in question.

getPath()

Gets the path down to an entity in the entity tree (including the entity itself).

Input parameters:

Upon sucess return the following ARRAY:

path => [ IDa, IDb .. IDz ]

where IDa and so on are the entity IDs from the database of the entity in the path down to the entity in question.

The first element of the array is the topmost element in the entity tree and then the succeeding elements descends down to the entity in question in correct order.

getType()

Gets the type name of an entity.

Input parameters:

Upon sucess returns the textual entity type name:

type = STRING # textual type name of entity

ping()

Pings the server to see if it floats or not.

No input accepted.

The method just checks that the server respons and is working and upon success returns just the global values of "received", "delievered", "err" and "errstr".

getTree()

Get the entity tree.

Input parameters:

Upon success will return the following HASH-structure:

tree => (
          IDa => (
                   id => INTEGER
                   parent => INTEGER,
                   type => STRING,
                   name => STRING,
                   metadata => (
                      metadataA => STRING,
                      .
                      .
                      metadataZ => STRING
                               )
                   children => [ IDb...IDn ]
                 )
          IDb => (
                   id => INTEGER,
                   parent => INTEGER,
                   type => STRING,
                   name => STRING,
                   metadata => (
                      metadataA => STRING,
                      .
                      .
                      metadataZ => STRING,
                               )
                   children => [],
                 )
          .
          .
          IDz => ( ... )
        )

All the information in the tree is flat, so that all entities resides in the first level of the HASH. Each sub-hash then refers to entities on the top level through its children array. All entities in the tree will return its id, parent, type, name and an array of its children (if any) except the top root-node (1), which does not have any parent. The entity type is the textual string version of the type (eg. "DATASET", "GROUP", "COMPUTER" and so on and so forth).

In addition to the set group of information like: id, parent, type, name and children, each sub-hash also includes a metadata sub-hash that contains metadata that might be relevant to the the entity. Eg. for GROUP-entities the fileinterface store-name will be included if it has been set at all.

AUTHENTICATION METHODS

changeAuth()

Changes the authentication data for a authentication type.

Parameters of this method are (beyond the standard auth-strings):

If the user to change the authentication for is not the currently authenticated user, the user performing the authentication change must have the USER_CHANGE-permission on the user entity in question.

The method returns 1 upon success or 0 upon failure (see documentation of restsrvc.pl for more information on the format of return values in the REST-server)

doAuth()

Performs an authentication test.

No input is needed as they are supplied as part of the authentication-strings to the REST-server.

Always return 1 (as it is impossible to run the method without valid authentication).

doDeAuth()

Removes any authentication tokens that may exist.

Requires the following input: authtype and authstr.

Returns 1 upon success, 0 upon failure.

enumAuthTypes()

Enumerates the authentications types that are defined as acceptable in the REST-servers settings file and are possible to instantiate. In other words it return the authentication schemes that are valid for the REST-server running.

No input is needed.

The return data structure contains the authtypes substructure like thus:

authtypes => ( "type" => ( change => INT # 0 or 1 for possible to change (1) or not(0). format => STRING # acceptable format of the authentication string maxlength => INT # maximum length of the authentication string regex => STRING # regex that checks the authentication string longevity => INT # the lifespan of a set of authentication details in AURORA. ) "typeN" => ( ) )

Please check the documentation of the Authenticator.pm-module for more information upon the meaning of the values in the returned structure. Type above means the textual authentication type, such as "AuroraID".

getAuthData()

Get public authenticator data for logged in user.

No input is accepted.

The method will attempt to retrieve any public authenticator data that er stored for logged in user.

The result upon success is returned as a HASH named data:

data => (
           AUTHDATAKEYa => STRING # value of given authetnicator data key
           .
           .
           AUTHDATAKEYz => STRING # value....
        )

The AUTHDATAKEY reflect the metadata namespace in the database where the value is stored. The metadata itself is stored on a USER-entity. It will also return the shared and general authentication data like so:

id => INTEGER # entity ID of logged on user
email => STRING # the email/unique username of the user
fullname => STRING # the full name of the user
displayname => STRING # the users display name

Please note that when it comes to the return data-HASH, which keys will appear depends upon which authenticator type the user used to log in with. Please see the documentation for the given Authenticator-class in question to know which namespaces key it stores and tags as public.

COMPUTER METHODS

createComputer()

Creates a computer entity.

Input parameters are the following:

The display name entered either as parameter "name" or as metadata (".system.entity.name") must be unique for a computer in the entire entity tree. If any other computer entity has the same display name, the method will fail in its attempt to create the entity.

The user calling this method must also have the COMPUTER_CREATE permission on the parent group in question.

The method only accepts non-system namespaced metadata (starting with ".").

deleteComputer()

Deletes a computer entity.

Input parameter is:

Methods requires the user to have the COMPUTER_DELETE permission on the given computer.

deleteComputerMetadata()

Deletes computer metadata.

Accepts the following parameters:

This method requires that the user has the COMPUTER_CHANGE permission on the computer entity in question.

The method only accepts non-system namespaced metadata key-values.

enumComputerPermTypes()

Enumerates the computer permission types that exists.

No input is accepted.

It returns a structure with all the valid permissions for a computer entity in the following structure:

types => (
           STRING,             
           STRING,
           STRING,
         (

which is an array containing all the computer entity permission types in a textual fashion.

enumComputers()

Enumerates all computer entities in the database.

No input is accepted.

The return structure is as follows:

computers => (
               INT => STRING,
               INT => STRING,
               .
               .
               INT => STRING
             (

where INT is the entity id from the database and STRING is the textual display name of the entity.

getComputerAggregatedPerm()

Gets the aggregated/inherited permissions of a user on a computer entity.

Input parameters are as follows:

Returns a structure of aggregated perms upon success:

perm => (
          PERMISSION_NAME,
          PERMISSION_NAME,
          .
          .
          PERMISSION_NAME
        )

where PERMISSION_NAME is the STRING representation of the permission type that the specified user has on the given entity object.

getComputerPerm()

Get the permissions on the computer object in question.

Input is the following:

Returns the following structure upon success:

perm => ( 
          grant => [ PERMISSIONa, PERMISSIONb .. PERMISSIONn ],
          deny =>  [ PERMISSIONd, PERMISSIONe .. PERMISSIONo ],
        )

The PERMISSION-values in the grant- or deny- arrays are STRING names of the permissions that have been set in either grant- or deny.

getComputerMetadata()

Fetches the open metadata of a computer entity (everything that starts with a dot ".").

Input parameters are as follows:

Upon success returns the following structure:

metadata => (
              KEYa  => VALUE,
              KEYb  => VALUE,
              .
              .
              KEYn  => VALUE,
            )

KEY is the name of the metadata key (STRING) and VALUE is the value (STRING) for that metadata key.

This method only returns metadata in the open non-system namespace (starting with a dot ".").

getComputerName()

Gets the display name of the computer.

Input parameters are:

Upon success returns the name:

name => STRING

where STRING is the textual name of the computer.

getComputersByPerm()

Get list of computers based upon a set of permissions.

Input parameters are:

The return structure upon success is:

computers => (
               INTEGERa => STRING,
               INTEGERb => STRING,
               .
               .
               INTEGERn => STRING,
             )

where INTEGER is the computer id from the database and STRING is the display name of the computer.

getComputerTunnelProtocols()

Gets the supported protocols for remote control on the computer specified.

Accepts only one input parameter: id. INTEGER. Required. It defines the entity ID from the AURORA database of the computer that one wishes to get the supported protocols of.

Upon success returns an ARRAY:

protocols = ["PROT1" .. "PROTn"]

where PROT1 and so on is the textual name of the protocol(s) supported.

listComputerFolder()

List the folder contents of a computer.

Input parameters are:

The method will use the Store-method defined in the computers StoreCollection metadata in the first get-store defined. It will attempt to utilize that Store-instance to list the contents of the computer folder.

Any double dots ("..") will be squashed.

Upon success the method returns the following structure:

class       => STRING
path        => STRING
useusername => [0||1] # says if username has been appended to datapath
username    => STRING # only present if useusername = 1.
folder => (
            F => (
                   FILENAMEa => (
                                  type => STRING # F (file)
                                  name => STRING # file name
                                  size => INTEGER # size of file in bytes
                                  datetime => INTEGER # datetime in UTC of file
                                )
                   .
                   .
                   FILENAMEn => (
                                  ....
                                )
                 )
            D =>
                 (
                   FOLDERNAMEa => (
                                    type => STRING # D (folder) 
                                    name => STRING # name of folder object 
                                    size => INTEGER # size of folder entry (not its contents)
                                    datetime => INTEGER # datetime in UTC of folder object.
                                 )
                   .
                   .
                   FOLDERNAMEn => ( ... )
                 )
            L => (
                   LINKNAMEa => (
                                  type => STRING # L (symlink)
                                  name => STRING # name of link object
                                  size => INTEGER # size of link entry (not its contents)
                                  datetime => INTEGER # datetime in UTC of link object
                                  target => STRING # name of target or source that symlink points to
                                )
                   .
                   .
                   LINKNAMEn => ( ... )
                 )
          )

Class is the Store-class used to get the folder-listing in textual format (eg. "Store::RSyncSSH"). Path is the complete path used on the local computer to access the folder being listed.

The folder return value contains a sub-structure that first defines the objects in that folder sorted in its type (either F for File, D for Folder or L for symlink). Under that we have FILENAMEx, FOLDERNAMEx and LINKNAMEx, which are the names of the objects of that given type (either File, Folder or Symlink). Under each named entry the data for each item is listed: type, size, name and datetime. The folder sub-structure can be read more about in the documentation of the Store-classes.

The "userusername" return value says if the computer has a policy that states if the username is to be added to the datapath defined for the computer entity. It is either 1 (true) or 0 (false) if this is enforced by policy. If the useusername value is 1, another value "username" is present that gives the username being added.

moveComputer()

Moves a computer entity to another part of the entity tree.

Input is:

The method requires the user to have COMPUTER_MOVE permission on the computer being moved and COMPUTER_CREATE on the parent group it is being moved to.

openComputerTunnel()

This method attempts to open a tunnel on a gatekeeper-server for a client to a computer in AURORA for remote access and control.

Accepts the following input parameteres:

This method required that the user calling the method has the COMPUTER_REMOTE-permission on the computer entity in question (as identified by the id-parameter).

The method also uses template-information for the computer entity that one tries to open a tunnel to.

The template is to have the following structure in AURORA:

.system.gatekeeper.script = "/whatever/path/to/gatekeeper-script"
.system.gatekeeper.host = "mygatekeeper.server.domain"
.system.gatekeeper.username = "username"
.system.gatekeeper.keyfile = "mykeyfile.gk_keyfile"
.system.gatekeeper.knownhosts = "KNOWNHOSTS_DATA"
.system.gatekeeper.protocols.RDP = 3389
.system.gatekeeper.protocols.VNC = 5900

Important to note here is that the keyfile that is used to connect to the gatekeeper-server needs to have an ending called ".gk_keyfile". The keyfile for the gatekeeper needs to reside in the sandbox-location of the AURORA-server (please see the sandbox-location in the settings-file). The protocols part of the structure can consist of as many protocols as one has available for the computers at the location in the AURORA entity tree that the template takes effect. Please note also that the protocols needs to have uppercase names. When calling the method, the uppercase protocol names specified here are the ones that will be valid for a computer in question.

Returns the following answer upon success:

tunnel => "GATEKEEPER-SERVER:PORT"

where PORT is the new port that is available for the client in question to use in order to reach the remote admin features of the computer in question. The GATEKEPPER-SERVER is the IPv4-converted A-record of the gatekeeper-server if forceipv4 is enabled.

setComputerMetadata()

Sets metadata on the computer entity.

Input parameters are:

The metadata input will only accept metadata in the non-system namespace (starting with ".").

The method requires the user to have the COMPUTER_CHANGE permission on the computer specified in order to succeed.

setComputerName()

Set the display name of the computer.

Input parameters:

Method requires the user to have the COMPUTER_CHANGE permission on the computer changing its name.

DATASET METHODS

changeDatasetExpireDate()

Change the dataset's expiration date.

This method takes the following parameters:

This method required that the user has the DATASET_DELETE-permission on the dataset in question. If the user wished to extend the expiration date of the dataset beyond the limit set in template(s) on the "extendlimit"-setting or beyond the maximum extension time per attempt to extend (extendmax), the user needs the DATASET_EXTEND_UNLIMITED-permission. Please note that in either case the DATASET_DELETE-permission is needed.

Changing expire-dates in AURORA relies on some settings through templates called:

- system.dataset.close.extendmax - system.dataset.close.extendlimit

These two settings are read from AURORA when the user attempts to change the expire date and the ones in effect through templates will be used.

The general rule is that the user with the DATASET_DELETE-permission can choose to extend the expire-date of the dataset with a maximum of "extendmax"-seconds per time he tries to change the expire date. Furthermore, he can only extend the expiration date of the dataset up until the "extendlimit"-settings, which is basically used as the number of seconds after the close-date of the dataset in question. So, the user cannot extend the expire-date of the dataset beyond this limit. In order to do that, the template(s) in effect needs to be changed or he needs to additionally have the DATASET_EXTEND_UNLIMITED- permission on the dataset, which are typically only given to administrators.

The user can however without any hindrances limit the expire-date down to the current time and basically then ask for the dataset to expire immediately. This will, however, not remove the dataset immediately, but start a voting-process on whether this is to be done or not.

Upon success this method returns the new expiredate that has been set:

expiredate => INTEGER

checkDatasetTemplateCompliance()

Checks the given metadata's compliance with the dataset aggregated template.

Input parameters are:

Returns the following structure:

   compliance => INTEGER  # Overall compliance. 0 for non-compliant, 1 for compliant.
   noncompliance => ARRAY # contains the names (STRING) of the metadata key(s) (or template key(s)) that are non-compliant. The ARRAY will be empty if metadata is compliant.
   metadata => (
                 KEYa => (
                           comment => STRING # textual explanation of what value(s) are required on this key.
                           compliance => INTEGER # 0 = non-compliant, 1 = compliant. Refer to this specific key.
                           default => STRING or ARRAY # default value(s) if none is specified. Comes from template.
                           flags => ARRAY # textual flags that are set, if any.
                           min => INTEGER # minimum number of values into this key. 0 = no minimum, N > 0 = minimum number needed
                           max => INTEGER # maximum number of values allowed in this key. 0 = no maximum, N > 0 = maximum allowed
                           reason => STRING # textual explanation why a key is not in compliance (if it is non-compliant).
                           regex => STRING # regex that are used to check the value specified to this key.
                           value => STRING or ARRAY # value from metadata into method or from template                                                     
                         )
                 .
                 .
                 KEYn => ( ... )
               )

For more information about the return structure (especially the metadata sub-structure), look at the setTemplate-method of the REST-server.

closeDataset()

Closes a dataset.

Input parameters are:

This method requires that the user has the DATASET_CLOSE permission on the dataset in question.

createDataset()

Creates a new dataset.

Input parameters are:

The method requires that the user has the DATASET_CREATE permission on the parent group in question. Furthermore, if the dataset is a automated dataset, the user also needs the COMPUTER_READ permission on the computer in question.

Upon success returns the id of the newly created dataset in the id-field:

id => INTEGER

createDatasetToken()

Create a dataset token.

Input parameters

Required permission:

Returns the following structure upon success:

token => STRING

deleteDatasetMetadata()

Delete metadata from a dataset.

Input parameters:

The dataset cannot have been removed, because then it is not allowed to delete metadata.

The method requires that the user has the DATASET_CHANGE permission on the specified dataset.

It is only permitted with the open namespace keys in the metadata (starting with "."). Other keys are removed from the input.

enumDatasetPermTypes()

Enumerates the dataset permission types.

No input is accepted.

Returns the dataset permission types in the following structure:

types => [ PERMa, PERMb .. PERMn ]

The PERMa and so on are the textual name of the permission type. The types are returned as an ARRAY of STRING.

extendDatasetToken()

Adjust expire time for a dataset token. An expired or removed token will be reinstated.

Input parameters

Required permission:

Returns the following structure upon success:

token => STRING

getDatasetAggregatedPerm()

Gets the inherited or aggretaed permission on a given dataset.

Input parameters are:

The result upon success is returned in the following structure:

perm => [ PERMa, PERMb .. PERMb ]

PERMa and so on is the textual name of the permission type. The perm-key is a ARRAY of STRING. The perm-key can be an empty array if user has no permissions on the given dataset.

getDatasetExpirePolicy()

Gets the open- and close expire policies in effect for a given dataset.

Accepted input parameters are:

This method returns both the open- and close expire policies in effect for a given dataset.

Upon success the method returns the following structure:

expirepolicy => (
                  open => (
                            lifespan => INTEGER
                            extendmax => INTEGER
                            extendlimit => INTEGER
                          )
                  close => (
                             lifespan => INTEGER
                             extendmax => INTEGER
                             extendlimit => INTEGER
                           )
                )

getDatasetLog()

Gets the log for the dataset.

Input parameters

Upon success the following structure is returned:

loglevel => STRING # the loglevel start point for the entries returned
log => (
         1 => (
                loglevel => STRING  # the loglevel of this, specific log-entry
                message  => STRING  # the textual string of the log entry itself
                time     => STRING  # unix datetime in hi-res of the log entry (eg. 12345678.1234). String of float.
                idx      => INTEGER # the auto-increment value of this log entry in the database
                tag      => STRING  # the textual tag string for the entry. Defaults to "NONE".
              )
         .
         .
         N => ( ... )
       )

The returned log entries are returned with the key as an INTEGER giving the correct timed order of the entries. The key is just a running number from 1 to N (depending on size of log).

The method requires that the user has the DATASET_LOG_READ permission on the given dataset.

getDatasetMetadata()

Gets the metadata of a dataset.

Input parameters are:

The returned information upon success is the following structure:

metadata => (
              KEYa => STRING
              KEYb => STRING
              .
              .
              KEYc => STRING
            )

KEY in this case is the textual name of the metadata key (STRING). It points to the value of that key, also being a STRING.

The method requires that the user has either the DATASET_READ, DATASET_CHANGE or DATASET_METADATA_READ permissions on the dataset specified.

It only returns metadata in the open namespace (starting with ".").

getDatasetPerm()

Gets the permissions on a given dataset entity (not inherited/aggregated).

Input parameters are:

The result upon success is returned in the following structure:

perm => (
          grant => [ PERMa, PERMb .. PERMn ]
          deny => [ PERMa, PERMb .. PERMn ]
        )

PERMa and so on are the textual permission that the given user has on the specified dataset. Permissions on a dataset itself are divided into "grant" and "deny" permissions. Deny is applied before grant.

getDatasetPerms()

Gets all the permission(s) on a given dataset entity, both inherited and what has been set and the effective perm for each user who has any permission(s).

Input parameter is:

Upon success the resulting structure returned is:

perms => (
           USERa => (
                      inherit => [ PERMa, PERMb .. PERMn ] # permissions inherited down on the dataset from above
                      deny => [ PERMa, PERMb .. PERMn ] # permissions denied on the given dataset itself.
                      grant => [ PERMa, PERMb .. PERMn ] # permissions granted on the given dataset itself. 
                      perm => [ PERMa, PERMb .. PERMn ] # effective permissions on the given dataset (result of the above)
                    )
           .
           .
           USERn => ( .. )
         )

USERa and so on are the USER entity ID from the database who have permission(s) on the given dataset. An entry for a user only exists if that user has any permission(s) on the dataset. The sub-key "inherit" is the inherited permissions from above in the entity tree. The "deny" permission(s) are the denied permission(s) set on the dataset itself. The "grant" permission(s) are the granted permission(s) set on the dataset itself. Deny is applied before grant. The sub-key "perm" is the effective or resultant permission(s) after the others have been applied on the given dataset.

The permissions that users has through groups on a given dataset are not expanded. This means that the group will be listed as having permissions on the dataset and in order to find out if the user has any rights, one has to check the membership of the group in question (if the user is listed there).

Permission information is open and requires no permission to be able to read. PERMa and so on are the textual permission type that are set on one of the four categories (inherit, deny, grant and/or perm). These four categories are ARRAYS of STRING. Some of the ARRAYS can be empty, although not all of them (then there would be no entry in the return perms for that user).

The perms-structure can be empty if no user has any permission(s) on the dataset.

getDatasets()

Search for and return datasets that match search criteria.

Input parameters are:

This method will only return datasets that the user has the necessary permission(s) on. In order for a dataset to be returned in the match (besides matching the given search criteria) the user must have one or more of the following permissions: DATASET_DELETE, DATASET_CHANGE, DATASET_MOVE, DATASET_PUBLISH, DATASET_RERUN, DATASET_PERM_SET, DATASET_READ, DATASET_LOG_READ or DATASET_LIST. Please see separate documentation for an explanation of the meaning of the various permissions.

Upon success the method will return the following HASH structure:

returned => INTEGER # number of returned matches (dependant upon count parameter)
total => INTEGER    # number of matches in total (of the search, irrespective of the count parameter)
metadata => ()      # HASH structure with the cleaned version of the metadata as used in the search
datasets => (
              1 => (
                     computerid => INTEGER  # computer entity id which is/was the source of the dataset
                     computername => STRING # textual name of computer which is/was the source of the dataset
                     created => STRING      # timedate in unixtime (UTC) of dataset creation time (hires time with microsecs - 12345678.54321). String of float.
                     creator => STRING      # textual name of the creator from metadata
                     creatorid => INTEGER   # user entity ID from database of creator at creation time (might not be the same as "creator" from metadata.)
                     description => STRING  # Dublin Core description metadata
                     expire => STRING       # timedate in unixtime (UTC) of dataset expiration time (hires time with microseconds - 12345678.54321). String of float.
                     id => INTEGER          # dataset entity ID from database
                     perm => ARRAY          # the permission(s) that the user has on the dataset
                     status => STRING       # current status of dataset (open, closed)
                     removed => STRING      # timedate when dataset was removed, or 0 if not removed yet.
                     type => STRING         # MANUAL or AUTOMATED.
                     parentid => INTEGER    # entity id of dataset parent
                     parentname => STRING   # textual name of dataset parent
                     entitytype => INTEGER  # entity type of dataset (which is dataset)
                   )
              .
              .
              N => ( ... )
            )

Some of the values placed in the datasets sub-hash are system metadata that are deemed necessary to be there and accessible/readable.

Lastly, some of the values in the datasets sub-hash are aggregates from other parts of the database, such as the perm-value (an aggregate of the users permissions on the dataset in question based on the entity tree).

The immediate key in the datasets sub-hash are numbers from 1 to N. These signify the order of the returned matches and are always numbered 1 to N, independant upon how the search window has been defined (see the offset- and count- parameters).

Please note that the "metadata" sub-hash will always be returned, even upon failure. It shows the metadata-structure as it was used after cleaning in the search. It is a good point to check if any of the search criteria keys have been removed because they are not allowed to be used in the search. This might lead to metadata-structures that are not usable by the REST-server and it fails its SQL-search.

getDatasetSystemAndMetadata()

Get a dataset's system- (only a subset) and open metadata.

Input parameters are:

The method will only retrieve a sub-set of the system metadata (see the getDatasetSystemMetadata method). All of the open metadata are also returned with the subset of the system metadata.

It is required for the user to have either DATASET_READ, DATASET_CHANGE or DATASET_METADATA_READ permission(s) on the dataset in question.

getDatasetSystemMetadata()

Get a sub-set of the dataset's system metadata (non-open metadata).

Input parameters are:

The method will only get a sub-set of the system metadata that are considered acceptable to deliver. Per today these are: dataset- status, created (datetime of creation), closed (datetime when it was closed), expire (datetime of expire time), deleted (if it has been deleted or not), type (AUTOMATED or MANUAL) and creator (who created the dataset).

It is required for the user to have either the DATASET_READ, DATASET_CHANGE or DATASET_METADATA_READ permission(s) on the dataset in question.

getDatasetTemplate()

Get the aggregated dataset template.

Input parameters are:

Upon success the following structure is returned:

  template = (
               KEYa => (
                         comment => STRING # textual explanation of what value(s) are required on this key.
                         default => STRING or ARRAY # default value(s) if none is specified. Comes from template.
                         flags => ARRAY # textual flags that are set, if any.
                         min => INTEGER # minimum number of values into this key. 0 = no minimum, N > 0 = minimum number needed
                         max => INTEGER # maximum number of values allowed in this key. 0 = no maximum, N > 0 = maximum allowed
                         regex => STRING # regex that are used to check the value specified to this key.
                       )
                 .
                 .
                 KEYn => ( ... )               
             )

For more information about the return structure (especially the metadata sub-structure), look at the setTemplate-method of the REST-server.

listDatasetFolder()

Lists the files- and folders- in the stored dataset.

Input parameters are:

This method requires that the user has the DATASET_READ permission on the dataset in question.

Upon success the following structure is returned:

folder => (
          ITEMNAMEa => (
                         "." => (
                                  name => STRING # name of the item, in this case a folder
                                  type => STRING # either D or F, in this case D for folder.
                                  size => INTEGER # size of item in bytes.
                                  atime => INTEGER # atime of item in unix datetime.
                                  mtime => INTEGER # mtime of item in unix datetime.
                                  md5 => STRING; # md5-sum of file, if enabled.
                                )
                         ITEMNAMEc => ( ... )
                         ITEMNAMEd => ( ... )
                         .
                         .
                         ITEMNAMEx
                       )
          ITEMNAMEb => (
                         "." => (
                                  name => STRING # name of item, in this case a file
                                  type => STRING # either D or F, in this case F for file.
                                  size => INTEGER # size of item in bytes.
                                  atime => INTEGER # atime of item in unix datetime.
                                  mtime => INTEGER # mtime of item in unix datetime.
                                )
                       )
          .
          .
          ITEMNAMEn
        )

The "folder" hash structure starts with the items in the top folder of the dataset. These items can be either files or folders. The name of this item is put into the sub-hash of the itemname under the "."-name. This is done for both files and folders (to maintain the similarity of the structure). The reason for folders is obviously because this information cannot be stored directly in the sub-hash as it may conflict with item-names in that folder. "." on the other hand signifies the folder itself and as such is also used for the file-item entries.

Each item in the returned result has a key called "type" and it is either filled with a "D" for folder or a "F" for file.

Error-messages on the md5 attribute will have the form: "N/A: Some Error Message".

moveDataset()

Move a dataset to another group entity.

Input parameters are:

This method requires that the user has the DATASET_MOVE permission on the dataset being moved and the DATASET_CREATE permission on the new parent group.

removeDataset()

Attempts to remove a dataset.

This method accepts the following input:

This method requires the DATASET_DELETE permission on the dataset in question.

It is not allowed to remove open datasets - they must be closed first. If the dataset is closed, calling this method will start a dataset remove notification-process that can eventually lead to the removal of the dataset by the Maintenance-service.

removeDatasetToken()

Remove a dataset token.

Input parameters

Required permission:

Returns the following structure upon success:

token => STRING

setDatasetMetadata()

Set the metadata of the dataset.

Input parameters are:

The method requires that the user has the DATASET_CHANGE permission on the dataset in question. It is also required that the dataset has not been removed prior to trying to set/update any metadata.

setDatasetPerm()

Set permissions on a dataset.

Input parameters are:

This method requires the user to have the DATASET_PERM_SET permission.

Upon success will return the following structure:

perm => (
          grant => ARRAY    # STRINGs of permissions set
          deny => ARRAY     # STRINGs of permissions set
        )

This will be the grant- and deny- permissions that have ended up being set.

GROUP METHODS

addGroupMember()

Add a member to a group.

Input parameters:

This method requires that the user has the GROUP_MEMBER_ADD permission.

assignGroupTemplate()

Assign a templates on a group.

Input parameters:

This method requires that the user has the GROUP_TEMPLATE_ASSIGN permission on the group in question.

createGroup()

Create a new group.

Input parameters:

The method requires that the user has the GROUP_CREATE permission on the parent group of the group being created.

The method will fail to create the group, if any template(s) in effect for the group are not compliant.

Upon success will return the following values:

id => INTEGER # group entity ID of the newly created group.
name => STRING # the resulting (after cleaning) textual name of the newly created group.

deleteGroup()

Delete a group.

Input parameters:

This method requires the user to have the GROUP_DELETE permission on the group being deleted.

It also requires that there are no children attached to the group being deleted. If so, these must either be moved somewhere else or deleted before attempting to delete the group in question.

enumGroupPermTypes()

Enumerate the group permissions types.

No input is accepted.

Upon success returns the following HASH-structure:

types => ARRAY of STRING # name(s) of the group permission types.

enumGroups()

Enumerate all the groups that exists.

No input parameters are accepted.

Upon success will return the following HASH-structure:

groups => (
            GROUPIDa => STRING # key->value, where key is the group entity ID and the value is the display name of the group.
            .
            .
            GROUPIDx => STRING
          )

getGroupAggregatedPerm()

Get inherited/aggregated permission(s) on the group for a user.

Input parameters:

Upon success this method will return the following value:

perm => ARRAY of STRING # textual names of the permimssion(s) the user has on the given group.

getGroupMembers()

Get the member(s) of a given group.

The following input parameters are accepted:

This method requires that the user has the GROUP_MEMBER_ADD permission.

Upon success will return the members of the given group in the following structure:

members => (
             MEMBERa => STRING # textual name of the given member entity.
             .
             .
             MEMBERx => STRING

           )

MEMBERa and so on is the entity ID (INTEGER) of one of the member(s) in the given group.

getGroupName()

Get the display name of the group.

Input parameters:

Upon success returns the following value:

name => STRING # the textual name of the group entity specified.

getGroupNoticeSubscriptions()

Get users notice subscriptions on a group.

Accepted parameters are:

Upon success this method returns the following structure:

subscriptions => {
                    USERa => {
                               NOTICEb => INTEGER # Value must be boolean true/false and will be converted to 0/1.
                               .
                               .
                               NOTICEz => INTEGER
                             }
                    .
                    .
                    USERz => { ... }
                 }

In this return structure "USERa" and so on is the user id from the database of the user that have subscription(s) to any of the notice classes. The next level in the HASH is the "NOTICEb" and so on, which is the notice id from the database of the notice that the user is subscribing to. Please note that this notice id is allowed to be 0 and will then signify that the user subscribes to all available Notice-classes.

getGroupPerm()

Get group permission(s) for a given user.

Input parameters:

Upon success returns the following structure:

perm => (
          grant => ARRAY of STRING # permission(s) that have been granted on this group.
          deny => ARRAY of STRING # permission(s) that have been denied on this group.
        )

Please note that when these permissions are used by the system, what it finds for deny is applied before the grant-part is applied when it comes to effective permissions.

getGroupPerms()

Gets all the permission(s) on a given group entity, both inherited and what has been set and the effective perm for each user who has any permission(s).

Input parameters:

Upon success the resulting structure returned is:

perms => (
           USERa => (
                      inherit => [ PERMa, PERMb .. PERMn ] # permissions inherited down on the group from above
                      deny => [ PERMa, PERMb .. PERMn ] # permissions denied on the given group itself.
                      grant => [ PERMa, PERMb .. PERMn ] # permissions granted on the given group itself. 
                      perm => [ PERMa, PERMb .. PERMn ] # effective permissions on the given group (result of the above)
                    )
           .
           .
           USERn => ( .. )
         )

USERa and so on are the USER entity ID from the database who have permission(s) on the given group. An entry for a user only exists if that user has any permission(s) on the group. The sub-key "inherit" is the inherited permissions from above in the entity tree. The "deny" permission(s) are the denied permission(s) set on the group itself. The "grant" permission(s) are the granted permission(s) set on the group itself. Deny is applied before grant. The sub-key "perm" is the effective or resultant permission(s) after the others have been applied on the given group.

The permissions that users has through groups on a given group are not expanded. This means that a group will be listed as having permissions on the group and in order to find out if the user has any rights, one has to check the membership of the group in question (if the user is listed there).

Permission information is open and requires no permission to be able to read. PERMa and so on are the textual permission type that are set on one of the four categories (inherit, deny, grant and/or perm). These four categories are ARRAYS of STRING. Some of the ARRAYS can be empty, although not all of them (then there would be no entry in the return perms for that user).

The perms-structure can be empty if no user has any permission(s) on the group.

getGroupsByPerm()

Get list of groups based upon a set of permissions.

Input parameters are:

The return structure upon success is:

groups => (
            INTEGERa => STRING,
            INTEGERb => STRING,
            .
            .
            INTEGERn => STRING,
          )

where INTEGER is the group id from the database and STRING is the display name of the computer.

getGroupTaskAssignments()

Gets a group's task assignments.

Input parameters are:

Returns a HASH of task IDs assignments upon success. See the setGroupTaskAssignments()-method for more information upon its structure.

getGroupUsersVotes()

Gets the user(s) votes on a given group (if any).

Accepted input parameters are:

Upon success this method returns the following HASH-structure:

votes => {
            USERa => INTEGER
            USERb => INTEGER
            .
            .
            USERz => INTEGER
         }

The "USERa", "USERb" and so on here is the user id from the database and the INTEGER value is the number of votes that the user has on the given group.

moveGroup()

Moves a group entity to another part of the enitty tree.

Input is:

The method requires the user to have the GROUP_MOVE permission on the group being moved and GROUP_CREATE on the parent group it is being moved to.

removeGroupMember()

Remove member(s) of a group.

Input parameters:

The method requires that the user has the GROUP_MEMBER_ADD permission on the group in question.

setGroupFileInterfaceStore()

Set the fileinterface(FI) store name on a given group entity.

Input accepts the following parameters:

This method requires the user to have the GROUP_FILEINTERFACE_STORE_SET permission on the group in question.

It also requires the store-name to abide with the characters limitations set on such a name by the FileInterface(FI) layer. The store must also already exist and have been put in place for it to be used. All of this will be checked against the FI-layer before any setting is saved to the group entity.

setGroupName()

Set/edit the display name of a group.

Input accepts the following parameters:

This method requires that the user has the GROUP_CHANGE permission on the group specified.

setGroupNoticeSubscriptions()

Sets the users notice subscriptions on a group.

Input parameters:

This methods required that the user has the GROUP_CHANGE-permission on the group in question. Please also note that the subscriptions hash must include all previous subscriptions as well as new ones, since this method is basically a replace-method.

The subscriptions HASH structure is to be as follows:

subscriptions => {
                    USERa => {
                               NOTICEb => INTEGER # Value must be boolean true/false and will be converted to 0/1.
                               .
                               .
                               NOTICEz => INTEGER
                             }
                    .
                    .
                    USERz => { ... }
                 }

In this return structure "USERa" and so on is the user id from the database of the user that have subscription(s) to any of the notice classes. The next level in the HASH is the "NOTICEb" and so on, which is the notice id from the database of the notice that the user is subscribing to. Please note that this notice id is allowed to be 0 and will then signify that the user subscribes to all available Notice-classes. We advise that notice-value is either set to 0 or 1, but it will be boolean-evaluated and then converted to 0/1 in any event.

When giving this method a HASH with the subscriptions settings, it will check that it contains valid user-references, valid notice-references and it will convert, as mentioned above, the notice value. If any value is not valid, it will be omitted from the HASH that is input to the system. This can in the worst case scenario create a situation where all current subscriptions on the given group are removed and none is set.

Upon success the method returns the subscriptions hash that was set in the key "subscriptions":

subscriptions => { ... }

setGroupPerm()

Set permission(s) on the given group for a user.

Input parameters are:

This method requires the user to have the GROUP_PERM_SET permission.

Upon success will return the following structure:

perm => (
          grant => ARRAY    # STRINGs of permissions set
          deny => ARRAY     # STRINGs of permissions set
        )

This will be the grant- and deny- permissions that have ended up being set.

unassignGroupTemplate()

Unassign all template(s) of a given type from a group.

Input parameters are:

This method requires that the user has the GROUP_TEMPLATE_ASSIGN permission on the group in question.

setGroupTaskAssignments()

Sets a group's task assignments.

Input parameters are:

This method requires that the user has the GROUP_CHANGE permission on the computer having its assignments set. Furthermore, the method requires that the user has the TASK_EXECUTE-permission on the task(s) being added to computers.

The HASH-structure of the assignments is as follows:

assignments => (
                 COMPUTERIDa => [TASKID1, TASKID2 .. TASKIDn]
                 .
                 .
                 COMPUTERIDz => ...
               )

Returns the assignments actually set upon success in the same structure as setting the assignments.

Please note that the assignments given to this method overrides any previous assignments. To achieve append functionality one will need to read the current assignments first and append to that on the input to this method.

setGroupUsersVotes()

Sets the users votes on a group.

Input parameters:

This methods requires that the user has the GROUP_CHANGE-permission on the group in question.

The votes-HASH is to have the following structure:

votes => {
            USERa => INTEGER
            USERb => INTEGER
            .
            .
            USERz => INTEGER
         }

"USERa", "USERb" and so on is the user id from the database of the user to set votes for. The INTEGER-value is the number of votes to give that user on the given group in question. Please note that the specified user ids as well as the value is checked for sanity and if they are not ok, they will be omitted from the votes-settings actually written to the database.

For more information on how the voting-process is working, consult the overview-documentation on the Notification-service.

Upon success, this method returns the votes-HASH that was set:

votes => { ... }

INTERFACE METHODS

deleteInterface()

Delete interface entity.

Input parameters:

This methods requires that the user has the INTERFACE_DELETE permission on the interface being deleted.

enumInterfaces()

Enumerates all the interfaces.

No input accepted.

Upon success returns the following structure:

interfaces => (
                 INTERFACEIDa => STRING # key-value pair. The key is the name of the field and STRING is the textual value of the key
                 .
                 .
                 INTERFACEIDn => ( .. )
              )

getInterface()

Gets an interface.

Input parameters are:

Returns the following structure upon success:

interface => (
               type => STRING            # MIME render type
               distinguisable => INTEGER # 1 for TRUE, 0 for FALSE.
               multiple => INTEGER       # 1 for TRUE, 0 for FALSE. Does it produce more than one mime-result?
               class => STRING # textual name of a render class, eg. Interface::CIFS.
               name => STRING  # textual display name of this renderer - often the same as the class
               classparam => HASH # subkey hash with parameters for the class instantiation. key->value.
             )

moveInterface()

Move an interface to another group.

Input parameters are this:

This method requires that the user has the INTERFACE_MOVE permission on the interface being moved and the INTERFACE_CREATE permission on the new parent.

renderInterface()

Renders an interface to a dataset.

Input parameters:

This method requires that the user has the DATASET_READ permission on the dataset being rendered.

This method can render any interface that the AURORA system is using. An interface is a way of getting access to a dataset, it may be as a ZIP- or TAR-file or as a URL and so on.

Upon success this method will return different structure dependant upon the status of the rendering. The rendering process might take time.

If the rendering was started successfully, but did not finish immediately, the structure will look like this:

rendered => INTEGER # this will be 0 signifying that it is still not rendered (=still rendering).
type => STRING # MIME-type of the rendered result
result => ARRAY of STRING # this is the rendered MIME-result - it may point to places where the rendered result can be downloaded.

If the rendering has completed successfully, the structure will look like here:

rendered => INTEGER # this will now be 1, as it is finished rendering.
type => STRING # MIME-type of the rendered result.
result => ARRAY of STRING # contains the rendered MIME-result - it might point elsewhere...

So, if a rendering of an interface is not finished yet, the user of will have to call this method several times with the same input (especially the paths-parameter). Differing paths-sets can create differing renders, although the order of the paths does not matter (it is sorted ascending). Eventually the method will return the "rendered"-parameter as completed/finished successfully.

setInterfaceName()

Set the display name of the interface.

Input parameters:

Method requires the user to have the INTERFACE_CHANGE permission on the computer changing its name.

unrenderInterface()

Unrenders an interface to a dataset.

Input parameters:

This method requires that the user has the DATASET_READ permission on the dataset being rendered.

It is important to get the parameters correct in order to unrender a interface that has already been rendered. Especially the "paths"-parameter needs to have the exact same relative paths, or else it will not work.

Upon success will return the following structure:

unrendered = INTEGER # 0 = not unrendered, 1 = unrendered
type = STRING # MIME-type of the render

This method can be called multiple times to check if it is finished rendering.

NOTICE METHODS

deleteNotice() - Delete a notice

Delete a notice.

Input parameters:

This method requires that the user has the NOTICE_DELETE permission on the notice in question.

enumNotices() - Enumerate all notices

Enumerates all the notice entities in the database.

No input accepted.

Upon success the return structure is as follows:

notices => (
             NOTICEIDa => STRING # key->value, where key is the notice entity ID and STRING is the display name of the notice-entity.
             .
             .
             NOTICEIDx => STRING
           )

moveNotice() - Move notice to another group parent

Move notice to another group parent.

Input parameters:

The method requires the user to have NOTICE_MOVE permission on the notice being moved and NOTICE_CREATE on the parent group it is being moved to.

setNoticeName()

Set/change the name of the notice.

Input parameters:

Method requires the user to have the NOTICE_CHANGE permission on the notice in question.

SCRIPT METHODS

createScript()

Create a new script.

Input parameters:

The method requires that the user has the SCRIPT_CREATE permission on the parent of the script being created.

The method will fail to create the script, if any template(s) in effect for the script are not compliant.

Upon success will return the following values:

id => INTEGER # script entity ID of the newly created script.
name => STRING # the resulting (after cleaning) textual name of the newly created script.

deleteScript()

Delete a script.

Input parameters:

This method requires the user to have the SCRIPT_DELETE permission on the script being deleted.

enumPermTypes()

Enumerate the script permissions types.

No input is accepted.

Upon success returns the following HASH-structure:

types => ARRAY of STRING # name(s) of the script permission types.

enumScripts()

Enumerate all the scripts that exists.

No input parameters are accepted.

Upon success will return the following HASH-structure:

scripts => (
            SCRIPTa => STRING # key->value, where key is the script entity ID and the value is the display name of the script.
            .
            .
            SCRIPTx => STRING
          )

getScript()

Gets a script's definition.

Input parameter is:

This method requires that the user has either the SCRIPT_READ or SCRIPT_CHANGE permission on the script in question.

Upon success returns the same structure as input to the setScript-method (see setScript()-method for more information).

getScriptName()

Get the display name of the script.

Input parameters:

Upon success returns the following value:

name => STRING # the textual name of the script entity specified.

getScriptPerm()

Get script permission(s) for a given user.

Input parameters:

Upon success returns the following structure:

perm => (
          grant => ARRAY of STRING # permission(s) that have been granted on this script.
          deny => ARRAY of STRING # permission(s) that have been denied on this script.
        )

Please note that when these permissions are used by the system, what it finds for deny is applied before the grant is applied when it comes to effective permissions.

getScriptPerms()

Gets all the permission(s) on a given script entity, both inherited and what has been set and the effective perm for each user who has any permission(s).

Input parameters:

Upon success the resulting structure returned is:

perms => (
           USERa => (
                      inherit => [ PERMa, PERMb .. PERMn ] # permissions inherited down on the script from above
                      deny => [ PERMa, PERMb .. PERMn ] # permissions denied on the given script itself.
                      grant => [ PERMa, PERMb .. PERMn ] # permissions granted on the given script itself. 
                      perm => [ PERMa, PERMb .. PERMn ] # effective permissions on the given script (result of the above)
                    )
           .
           .
           USERn => ( .. )
         )

USERa and so on are the USER entity ID from the database who have permission(s) on the given script. An entry for a user only exists if that user has any permission(s) on the script. The sub-key "inherit" is the inherited permissions from above in the entity tree. The "deny" permission(s) are the denied permission(s) set on the script itself. The "grant" permission(s) are the granted permission(s) set on the script itself. Deny is applied before grant. The sub-key "perm" is the effective or resultant permission(s) after the others have been applied on the given script.

The permissions that users has through groups on a given script are not expanded. This means that a group will be listed as having permissions on the script and in order to find out if the user has any rights, one has to check the membership of the group in question (if the user is listed there).

Permission information is open and requires no permission to be able to read. PERMa and so on are the textual permission type that are set on one of the four categories (inherit, deny, grant and/or perm). These four categories are ARRAYS of STRING. Some of the ARRAYS can be empty, although not all of them (then there would be no entry in the return perms for that user).

The perms-structure can be empty if no user has any permission(s) on the script.

moveScript()

Moves a script entity to another part of the entity tree.

Input is:

The method requires the user to have the SCRIPT_MOVE permission on the script being moved and GROUP_CREATE on the parent it is being moved to.

setScript()

Sets the script definition.

Input parameters are:

The script code is the raw code of the script itself, with all special characters, new lines etc.

This method required the user to have the SCRIPT_CHANGE permission on the script having its code and/or name set.

setScriptName()

Set/edit the display name of a script.

Input accepts the following parameters:

This method requires that the user has the SCRIPT_CHANGE permission on the script specified.

setScriptPerm()

Set permission(s) on the given script for a user.

Input parameters are:

This method requires the user to have the SCRIPT_PERM_SET permission.

Upon success will return the following structure:

perm => (
          grant => ARRAY    # STRINGs of permissions set
          deny => ARRAY     # STRINGs of permissions set
        )

This will be the grant- and deny- permissions that have ended up being set.

STORE METHODS

deleteStore()

Delete a store entity.

Input parameters:

This method requires that the user has the STORE_DELETE permission on the store in question.

enumStoreRequiredParameters()

Enumerate all parameters required by a store.

Input parameters are:

Upon success returns the following HASH-structure:

parameters = (
               PARAMETER1 = (
                              value = STRING # current value
                              private = INTEGER # is the parameter private to the class or not (0/1)?
                              regex = STRING # regex to check the value against
                              escape = INTEGER # is the value to be escaped (0/1)?
                              required = INTEGER # is the value required or not (0/1)? Obviously always 1 here.
                              name = STRING # name of the parameter
                            )
               .
               .
               PARAMETERn = ( ... )
             )

enumStores()

Enumerates all the store entities in the database.

No input accepted.

Upon success the return structure is as follows:

stores => (
            STOREIDa => STRING # key->value, where key is the store entity ID and STRING is the display name of the store-entity.
            .
            .
            STOREIDx => STRING
          )

STOREIDa and so on is the store entity ID from the database (INTEGER).

moveStore()

Move store to another group parent.

Input parameters:

The method requires the user to have STORE_MOVE permission on the notice being moved and STORE_CREATE on the parent group it is being moved to.

setStoreName()

Set/change the display name of a store.

Input parameters:

Method requires the user to have the STORE_CHANGE permission on the store changing its name.

TASK METHODS

createTask()

Create a new task.

Input parameters:

The method requires that the user has the TASK_CREATE permission on the parent of the task being created.

The method will fail to create the task, if any template(s) in effect for the task are not compliant.

Upon success will return the following values:

id => INTEGER # task entity ID of the newly created task.
name => STRING # the resulting (after cleaning) textual name of the newly created task.

deleteTask()

Delete a task.

Input parameters:

This method requires the user to have the TASK_DELETE permission on the task being deleted.

enumTaskPermTypes()

Enumerate the task permissions types.

No input is accepted.

Upon success returns the following HASH-structure:

types => ARRAY of STRING # name(s) of the task permission types.

enumTasks()

Enumerate all the tasks that exists.

No input parameters are accepted.

Upon success will return the following HASH-structure:

tasks => (
            TASKIDa => STRING # key->value, where key is the task entity ID and the value is the display name of the task.
            .
            .
            TASKIDx => STRING
          )

getTask()

Gets a task definition.

Input parameter is:

This method requires that the user has either the TASK_READ or TASK_CHANGE permission on the task in question.

Upon success returns the same structure as input to the setTask-method (see setTask()-method for more information).

getTaskAggregatedPerm()

Get inherited/aggregated permission(s) on the task for a user.

Input parameters:

Upon success this method will return the following value:

perm => ARRAY of STRING # textual names of the permimssion(s) the user has on the given task.

getTaskName()

Get the display name of the task.

Input parameters:

Upon success returns the following value:

name => STRING # the textual name of the task entity specified.

getTaskPerm()

Get task permission(s) for a given user.

Input parameters:

Upon success returns the following structure:

perm => (
          grant => ARRAY of STRING # permission(s) that have been granted on this task.
          deny => ARRAY of STRING # permission(s) that have been denied on this task.
        )

Please note that when these permissions are used by the system, what it finds for deny is applied before the grant-part is applied when it comes to effective permissions.

getTaskPerms()

Gets all the permission(s) on a given task entity, both inherited and what has been set and the effective perm for each user who has any permission(s).

Input parameters:

Upon success the resulting structure returned is:

perms => (
           USERa => (
                      inherit => [ PERMa, PERMb .. PERMn ] # permissions inherited down on the task from above
                      deny => [ PERMa, PERMb .. PERMn ] # permissions denied on the given task itself.
                      grant => [ PERMa, PERMb .. PERMn ] # permissions granted on the given task itself. 
                      perm => [ PERMa, PERMb .. PERMn ] # effective permissions on the given task (result of the above)
                    )
           .
           .
           USERn => ( .. )
         )

USERa and so on are the USER entity ID from the database who have permission(s) on the given task. An entry for a user only exists if that user has any permission(s) on the task. The sub-key "inherit" is the inherited permissions from above in the entity tree. The "deny" permission(s) are the denied permission(s) set on the task itself. The "grant" permission(s) are the granted permission(s) set on the task itself. Deny is applied before grant. The sub-key "perm" is the effective or resultant permission(s) after the others have been applied on the given task.

The permissions that users has through groups on a given task are not expanded. This means that a group will be listed as having permissions on the task and in order to find out if the user has any rights, one has to check the membership of the group in question (if the user is listed there).

Permission information is open and requires no permission to be able to read. PERMa and so on are the textual permission type that are set on one of the four categories (inherit, deny, grant and/or perm). These four categories are ARRAYS of STRING. Some of the ARRAYS can be empty, although not all of them (then there would be no entry in the return perms for that user).

The perms-structure can be empty if no user has any permission(s) on the task.

getTasksByPerm()

Get list of tasks based upon a set of permissions.

Input parameters are:

The return structure upon success is:

tasks => (
            INTEGERa => STRING,
            INTEGERb => STRING,
            .
            .
            INTEGERn => STRING,
          )

where INTEGER is the task id from the database and STRING is the display name of the computer.

moveTask()

Moves a group entity to another part of the enitty tree.

Input is:

The method requires the user to have the TASK_MOVE permission on the task being moved and [COMPUTER|GROUP|USER]_CREATE on the parent it is being moved to.

setTask()

Sets the task definition.

Input parameters are:

The task HASH structure is as follows:

name => STRING # name of task itself
task => (
           get  => (      # all the get-operations to run on computer
                     1 => (
                            name => STRING
                            store => INTEGER
                            classparam => (
                                            someparam => STRING,
                                            someotherparam => STRING,
                                          )
                            param => (
                                       param1 => STRING,
                                       param2 => STRING,
                                     )
                          )
                     .
                     .
                     N = ( ... )

                   )
           put  => ( ... )     # all the put-operations to run on computer
        )

The task definition basically defines the set of get- and put- operations to run on a computer when it archives. Manual datasets only utilizes the "put"-part of the task, since the data in that type of dataset is put in place manually by the user. When it comes to automated datasets, the "get"-part is run first in order to fetch the data. The "get"-part can contain several Store-types to fetch data and various parameters. Both the "get" and "put" part of the task has the same structure and can contain several elements or operations numbered 1 to N.

When the "get"-process is finished successfully, if run at all as with manual datasets, the "put"-processes are run. The put-process is basically triggered by the dataset being closed.

Be aware also that tasks can be run manually by the user.

This method required the user to have the TASK_CHANGE permission on the task having its definition set.

setTaskName()

Set/edit the display name of a task.

Input accepts the following parameters:

This method requires that the user has the TASK_CHANGE permission on the task specified.

setTaskPerm()

Set permission(s) on the given task for a user.

Input parameters are:

This method requires the user to have the TASK_PERM_SET permission.

Upon success will return the following structure:

perm => (
          grant => ARRAY    # STRINGs of permissions set
          deny => ARRAY     # STRINGs of permissions set
        )

This will be the grant- and deny- permissions that have ended up being set.

TEMPLATE METHODS

createTemplate()

Creates a template with a given name.

Input parameters are:

This method requires that the user has the TEMPLATE_CREATE permission on the parent group in question.

Upon success returns the following structure:

id => INTEGER # template entity ID from the database of the newly created template.
name => STRING # the actual name that was set for the newly created template (after cleaning).

checkTemplateCompliance()

Checks the compliance of the template with the metadata input.

Valid parameters are:

The metadata-parameter HASH needs to be structured as follows:

metadata => (
              NAMEa => STRING,
              NAMEb => STRING,
              .
              .
              NAMEc => STRING
            )

The metadata HASH is basically a key->value collection of the metadata keys and its values to check against the aggregated template of the entity in question.

Upon success will return the following HASH-structure:

   compliance => INTEGER # Overall compliance, 0 for non-compliant, 1 for compliant.
   noncompliance => ARRAY of STRING # names of the metadata key(s)/template key(s) that are non-compliant, if any.
   metadata => (
                 KEYa => (
                           comment => STRING # textual explanation of what value(s) are required on this key.
                           compliance => INTEGER # 0 = non-compliant, 1 = compliant. Refer to this specific key.
                           default => STRING or ARRAY # default value(s) if none is specified. Comes from template.
                           flags => ARRAY # textual flags that are set, if any.
                           min => INTEGER # minimum number of values into this key. 0 = no minimum, N > 0 = minimum number needed
                           max => INTEGER # maximum number of values allowed in this key. 0 = no maximum, N > 0 = maximum allowed
                           reason => STRING # textual explanation why a key is not in compliance (if it is non-compliant).
                           regex => STRING # regex that are used to check the value specified to this key.
                           value => STRING or ARRAY # value from metadata into method or from template                                                     
                         )
                 .
                 .
                 KEYn => ( ... )
               )

The compliance flag on each metadata key signals if that particular key is in compliance or not. 0 means non-compliant, 1 means compliant. If a key is not compliant the "reason"-value above will be filled in with the textual reason for why it failed?

For a more exhaustive explanation of the template constraint values, see the setTemplate()-method.

deleteTemplate()

Deletes a template.

Input parameters are:

This method requires that the user has the TEMPLATE_DELETE permission on the template in question.

enumTemplateFlags()

Enumerate all template flag types.

No input accepted.

Returns an ARRAY structure as follows upon success:

flags => ["FLAGNAME1" .. "FLAGNAMEn"]

enumTemplatePermTypes()

Enumerate the template permission types.

Accepts no input.

Upon success will return the following ARRAY:

types => (
            PERMISSIONa
            PERMISSIONb
            .
            .
            PERMISSIONz
         )

where PERMISSIONa and so on is the name of the template permission (STRING).

enumTemplates()

Enumerates all the templates.

No input is accepted.

Upon success will return the following HAHS-structure:

templates => (
               IDa => STRING
               IDb => STRING
               .
               .
               IDz => STRING
             )

where IDa and so on is the template entity ID from the database (INTEGER) and the STRING is the name of the template.

getEntityTemplateAssignments()

Get the template assignment(s) on an entity.

Input parameters are:

Upon success returns the following HASH-structure:

assignments = (
                TYPEa = [TEMPLATEID1,TEMPLATEID2 .. TEMPLATEIDn]
                .
                .
                TYPEz = [ .. ]                         
              )

TYPEa and so on are the textual name of the type that the templates are assigned as. All template assignments in the AURORA-system are assigned to an entity with the type that it is to have effect as. A template of itself is entity type neutral until it is assigned. If no assignments are found, the structure will be empty. Each type point to an ARRAY of template entity IDs that are assigned to that type. The order of the array denotes the order in which the templates have effect from element 1 to N.

getAggregatedTemplate()

Gets the aggregated template of an entity.

Input parameters are:

Upon success returns the following HASH-structure:

id => INTEGER # id of the entity that the aggregated template was retrieved for
type => STRING # the textual entity type that we aggregated a template for (after cleaning)
template => (
              KEYa => (
                        default => STRING or ARRAY of STRING
                        flags => ARRAY of STRING
                        regex => STRING
                        min => INTEGER
                        max => INTEGER
                        comment => STRING
                      )
              KEYb => ( ... )
              .
              .
              KEYz => ( ... )
            )

Please see the setTemplate()-method for more information upon the structure of the constraints.

This method aggregates together templates of a given type down the entity tree and then returns one template definition for each key in question that is the result. It also defaults values that has defaults defined, since an aggregate is what is being used to determine the validitiy of values saved into the metadata of the AURORA- system and as such need them. Regex defaults to ".*", min defaults to 0, max to 1, flags to empty ARRAY (no flags set), comment to undef.

getTemplate()

Gets a specific template's defined constraints.

Input parameters:

This method gets the non-aggregated and specified template definition from the database. Upon success the method returns the following HASH-structure:

name => STRING
template => (
              KEYa => (
                        default => STRING or ARRAY of STRING
                        flags => ARRAY of STRING
                        regex => STRING
                        min => INTEGER
                        max => INTEGER
                        comment => STRING
                      )
              KEYb => ( ... )
              .
              .
              KEYz => ( ... )
            )

Please see the setTemplate()-method for more exhaustive explanation of the various parts of this structure.

As opposed to the getAggregatedTemplate()-method, this method only returns the specific template asked for. There is no aggregate here. Because of this the various constraints in the template (default, flags, regex etc.) can be undefined, since that is how it was defined.

getTemplateAssignments()

Get a templates assignment(s) on entities (if any).

Input parameters are:

Upon success returns the following HASH-structure:

assignments = (
                all => [ENTITYID1,ENTITYID2 .. ENTITYIDn]
                types => (
                           TYPEa = [ENTITYID1,ENTITYID2 .. ENTITYIDn]
                           .
                           .
                           TYPEz = [ .. ] 
                         )
              )

The top keys of the returned values are "all" and "types". The "all" key contains all unique entity IDs that are assigned to the given template, while "types" shows the distribution of assignments on various entity types. TYPEa and so on are the textual name of the type that the template is assigned as. All template assignments in the AURORA-system are assigned to an entity with the type that it is to have effect as. A template of itself is entity type neutral until it is assigned. If no assignments are found, the structure will be empty. Each type point to an ARRAY of entity IDs that are assigned to that type for the template in question.

getTemplateAggregatedPerm()

Gets the inherited/aggregated permissions on a template for a user.

Input parameters are:

Upon success this method will return the following value:

perm => ARRAY of STRING # textual names of the permimssion(s) the user has on the given template.

getTemplatePerm()

Get template permission(s) for a given user.

Input parameters:

Upon success returns the following structure:

perm => (
          grant => ARRAY of STRING # permission(s) that have been granted on this template.
          deny => ARRAY of STRING # permission(s) that have been denied on this template.
        )

Please note that when these permissions are used by the system, what it finds for deny is applied before the grant-part is applied when it comes to effective permissions.

getTemplatePerms()

Gets all the permission(s) on a given template entity, both inherited and what has been set and the effective perm for each user who has any permission(s).

Input parameter is:

Upon success the resulting structure returned is:

perms => (
           USERa => (
                      inherit => [ PERMa, PERMb .. PERMn ] # permissions inherited down on the template from above
                      deny => [ PERMa, PERMb .. PERMn ] # permissions denied on the given template itself.
                      grant => [ PERMa, PERMb .. PERMn ] # permissions granted on the given template itself. 
                      perm => [ PERMa, PERMb .. PERMn ] # effective permissions on the given template (result of the above)
                    )
           .
           .
           USERn => ( .. )
         )

USERa and so on are the USER entity ID from the database who have permission(s) on the given template. An entry for a user only exists if that user has any permission(s) on the template. The sub-key "inherit" is the inherited permissions from above in the entity tree. The "deny" permission(s) are the denied permission(s) set on the template itself. The "grant" permission(s) are the granted permission(s) set on the template itself. Deny is applied before grant. The sub-key "perm" is the effective or resultant permission(s) after the others have been applied on the given template.

The permissions that users has through groups on a given template are not expanded. This means that the group will be listed as having permissions on the template and in order to find out if the user has any rights, one has to check the membership of the group in question (if the user is listed there).

Permission information is open and requires no permission to be able to read. PERMa and so on are the textual permission type that are set on one of the four categories (inherit, deny, grant and/or perm). These four categories are ARRAYS of STRING. Some of the ARRAYS can be empty, although not all of them (then there would be no entry in the return perms for that user).

The perms-structure can be empty if no user has any permission(s) on the template.

moveTemplate()

Moves a template entity to another part of the entity tree.

Input is:

The method requires the user to have TEMPLATE_MOVE permission on the template being moved and TEMPLATE_CREATE on the parent group it is being moved to.

setTemplate()

Set template constraints.

Input parameters:

This method requires that the user has the TEMPLATE_CHANGE permission on the template in question.

The input template HASH structure must have the following layout:

template => (
              KEYNAMEa => (
                            default => STRING or ARRAY of STRING # defines the default values for this key.
                            regex => STRING # defines the regex that is going to check the value(s) of this key
                            flags => ARRAY of STRING # the template flags set on this key
                            min => INTEGER # the minimum number of values that has to be set.
                            max => INTEGER # the maximum number of values that can be set.
                            comment => STRING # textual explanation of what is needed to satisfy the regex
                          )
              .
              .
              KEYNAMEx => ( ... )
            )

KEYNAMEa and so on is the textual name of the metadata key in the namespace to set a template constraint for (eg. ".system.entity.name").

Default sub-key defines the default value(s) that will be chosen if no value has been specified. The default value(s) can also be used to specify a list of choices if using the flags SINGULAR or MULTIPLE (see further down for explanation of flags). The default value can be either a STRING (if its just one value) or an ARRAY of STRING (multiple values).

Regex is the regex that is used to check the value(s) entered when applying the template. If there are multiple values entered, the same regex will be used on all values. Please also note that a beginning (^) and end sign ($) will be applied around the regex entered, so that it represents something that needs to be matched within the beginning and end of the string being checked.

Flags are various markers for how the template key is to be used or applied. The flags are set as an ARRAY of STRING. Valid flag values are:

Min sets the minimum number of value(s) to be entered for the key in question. 0 means no minimum and everything above 0 means that that number is the minimum, so that the user needs to enter that number of value(s) or more. Default value if none is set here is 0 for aggregated templates.

Max sets the maximum number of value(s) that can be entered for the key in question. 0 means no maximum and everything above 0 means that that number is the maximum. Default values if none is set here is 1 for aggregated templates.

Comment sets the textual explanation of the regex and what this key expects to be filled in.

setTemplateName()

Set/change the name of the template.

Input parameters:

Method requires the user to have the TEMPLATE_CHANGE permission on the entities in question.

setTemplatePerm()

Set permissions on a template.

Input parameters are:

This method requires the user to have the TEMPLATE_PERM_SET permission.

Upon success will return the following structure:

perm => (
          grant => ARRAY    # STRINGs of permissions set
          deny => ARRAY     # STRINGs of permissions set
        )

This will be the grant- and deny- permissions that have ended up being set.

USER METHODS

createUser()

Create a user.

Input parameters:

This method requires that the user has the USER_CREATE permission on the group that is the parent. Please note that it is assumed that if the user has this permission on the parent, he is also allowed to create sub-groups in the event of the balanced-parameter being true.

The balancing scheme works as follows: the first letter of a users first name is used to determine what sub-group the user should be put in. If the group does not exist, it will be created. Furthermore, if the first letter contains a character outside the ASCII-table, it is changed to a letter within A-Z (lower cases are uppercased). This is done by first converting any character that is a variant upon A-Za-z, such as Ä, ë, ô etc and they are changed to their base character (A, e and o in this case). If this does not change the first letter within A-Z, it is changed algorithmatically by placing it somewhere within A-Z. The last enforcement might not be logical based upon the original character, but is done to ensure that only the sub-groups A-Z are created and used.

It is not allowed for more than one user having one, specific email-address in the entire entity tree. Also note that attempting to create a user with the email: zombie_[N]@localhost, where N is a number, is not allowed. These email addresses are reserved for accounts that are deleted/GDPRed.

Upon success returns the following HASH structure:

id => INTEGER # database entity ID of the newly created user.
username => STRING # the username used (email) of the created user after cleaning.

When this method is successful it is also sent a message to the new user with a temporary password and information about the account creation in AURORA.

deleteUser()

Anonymize (GDPR) a USER account.

Input parameters are:

This method requires the user to either have the USER_DELETE permission on the USER entity in question or be the user that is to be anonymized.

Where the user is moved in the event of setting the retire-parameter to true is defined in the system settings file. This enables all users to say that they wished to be moved after being GDPR'ed/deleted.

If the user himself or herself it calling this method, please remember that there is something about sawing off the branch of the tree one is sitting on and might lead to unplanned and unwanted encounters with gravity and pesky login-pages.

enumUsers()

Enumerates all user entities in the database.

No input is accepted.

The return structure is as follows:

users => (
           IDa => STRING,
           IDb => STRING,
           .
           .
           IDz => STRING
         (

where IDa and so on is the entity id from the database and STRING is the textual display name of the user.

getUserAggregatedPerm()

Get inherited/aggregated permission(s) on the user for a user.

Input parameters:

Upon success this method will return the following value:

perm => ARRAY of STRING # textual names of the permimssion(s) the user has on the given user

getUserTaskAssignments()

Gets a user's task assignments.

Input parameters are:

Returns a HASH of task IDs assignments upon success. See the setUserTaskAssignments()-method for more information upon its structure.

getUserEmail()

Gets a users email address

Input parameters:

This method requires that the user has the USER_READ or USER_CHANGE permissions.

Upon success the following structure is returned:

email => STRING # the email of the user

getUserFullname()

Get a users full name (first name and last name)

Input parameters:

Upon success returns the following structure:

fullname => STRING # the full name of the user entity ID specified on input

getUserId()

Get a users entity ID based on email/username.

Input parameters:

Upon success and the email address is valid will return the following structure:

id => INTEGER # the user entity ID of the email specified in the input.

getUserPerm()

Get user permission(s) for a given user.

Input parameters:

Upon success returns the following structure:

perm => (
          grant => ARRAY of STRING # permission(s) that have been granted on this user.
          deny => ARRAY of STRING # permission(s) that have been denied on this user.
        )

Please note that when these permissions are used by the system, what it finds for deny is applied before the grant-part is applied when it comes to effective permissions.

getUserPerms()

Gets all the permission(s) on a given user entity, both inherited and what has been set and the effective perm for each user who has any permission(s).

Input parameters:

Upon success the resulting structure returned is:

perms => (
           USERa => (
                      inherit => [ PERMa, PERMb .. PERMn ] # permissions inherited down on the user from above
                      deny => [ PERMa, PERMb .. PERMn ] # permissions denied on the given user itself.
                      grant => [ PERMa, PERMb .. PERMn ] # permissions granted on the given user itself. 
                      perm => [ PERMa, PERMb .. PERMn ] # effective permissions on the given user (result of the above)
                    )
           .
           .
           USERn => ( .. )
         )

USERa and so on are the USER entity ID from the database who have permission(s) on the given user. An entry for a user only exists if that user has any permission(s) on the user. The sub-key "inherit" is the inherited permissions from above in the entity tree. The "deny" permission(s) are the denied permission(s) set on the user itself. The "grant" permission(s) are the granted permission(s) set on the user itself. Deny is applied before grant. The sub-key "perm" is the effective or resultant permission(s) after the others have been applied on the given user.

The permissions that users has through groups on a given user are not expanded. This means that a group will be listed as having permissions on the user and in order to find out if the user has any rights, one has to check the membership of the group in question (if the user is listed there).

Permission information is open and requires no permission to be able to read. PERMa and so on are the textual permission type that are set on one of the four categories (inherit, deny, grant and/or perm). These four categories are ARRAYS of STRING. Some of the ARRAYS can be empty, although not all of them (then there would be no entry in the return perms for that user).

The perms-structure can be empty if no user has any permission(s) on the user.

moveUser()

Moves a user entity to another part of the entity tree.

Input is:

The method requires the user to have USER_MOVE permission on the user being moved and USER_CREATE on the parent group it is being moved to.

setUserTaskAssignments()

Sets a user's task assignments.

Input parameters are:

This method requires that the user has the USER_CHANGE permission on the user having its assignments set (typically every user has this permission on themselves). Furthermore it requires that the user has the TASK_EXECUTE-permission on the task(s) being assigned to computers.

The HASH-structure of the assignments is as follows:

assignments => (
                 COMPUTERIDa => [TASKID1, TASKID2 .. TASKIDn]
                 .
                 .
                 COMPUTERIDz => ...
               )

Returns the assignments actually set upon success in the same structure as setting the assignments.

Please note that the assignments given to this method overrides any previous assignments. To achieve append functionality one will need to read the current assignments first and append to that on the input to this method.