Scripting API reference

Constants

Directory entry type flags

  • DET_ALL.
  • DET_ASSEMBLY.
  • DET_FOLDER.
  • DET_LINK.
  • DET_MESSAGE.
  • DET_PROCESS.
  • DET_PROCESSOR.
  • DET_ROLE.
  • DET_SERVICE_CONTAINER.
  • DET_SET.
  • DET_STATE.
  • DET_WORKFLOW.

Sort orders

  • SORT_DEFAULT.
  • SORT_BY_NAME.
  • SORT_BY_UPDATE_TIMESTAMP.
  • SORT_BY_CREATION_TIMESTAMP.

Sort directions

  • ASC.
  • DESC.

BLOB formats

  • BLOB_FORMAT_TEXT.
  • BLOB_FORMAT_BIN.
  • BLOB_FORMAT_GZIP.

Permissions

  • READ.
  • WRITE.
  • CREATE_CHILDREN.

Directory object

The directory object provides the scripting API with the low-level directory interface. The object is available via the global variable $dir.

$dir.getPathById(id)

Returns the path of an entry with a specified id.
  • id - the id of an existing entry.

$dir.get(what)

Returns an entry with its payload by its path or id or null if the entry doesn't exist.
  • what - the path or id of the entry.

$dir.getInfo(what)

Returns an entry without its payload by its path or id or null if the entry doesn't exist.
  • what - the path or id of the entry.

$dir.getChildren(parent, entryTypes, property, order, offset, limit)

Returns child entries of an entry. The entries are returned with their payload.

If the parent entry doesn't exist, an empty collection is returned.
  • parent - the path or id of the parent.
  • entryTypes - the flags specifying entries of which type to return.
  • property - the property by which the entries are to be sorted.
  • order - the sorting order.
  • offset - the zero based index of the first returned entry among found.
  • limit - the upper limit on the indexes to return, so that max. entries returned = limit - offset. The limit less or equal to the offset means no limit.

$dir.getChildrenInfo(parent, entryTypes, property, order, offset, limit)

Returns child entries of an entry. The entries are returned without their payload.

If the parent entry doesn't exist, an empty collection is returned.
  • parent - the path or id of the parent.
  • entryTypes - the flags specifying entries of which type to return.
  • property - the property by which the entries are to be sorted.
  • order - the sorting order.
  • offset - the zero based index of the first returned entry among found.
  • limit - the upper limit on the indexes to return, so that max. entries returned = limit - offset. The limit less or equal to the offset means no limit.

$dir.countChildren(parent, entryTypes)

Counts the number of children of an entry.

If the specified parent entry doesn't exist, returns zero.
  • parent - the path or id of the parent.
  • entryTypes - the flags specifying entries of which type to count.

$dir.getAncestor(child, n, ancestorEntryTypes)

Finds the n-th nearest ancestor of an entry and returns it with payload.

If the child is specified as a path, the deepest existing entry on the path is searched and the operation is performed against it. For example, suppose one requests 0-th ancestor of type Set by the path '/Sets/Shared/Set/Subset' where 'Set' is a set and it exists, 'Subset' is a subset and it doesn't exist. Then, the set '/Sets/Shared/Set' is returned.

If the child is specified by id and it doesn't exists, exception is thrown.
  • child - The id of an entry or path starting from which to search for the ancestor.
  • n - How many found ancestors to skip assuming that the search starts from the child entry itself. For example, if n = 0, and the child entry satisfies ancestorEntryTypes filter, than the child entry is returned itself. If, in the same case, n = 1, the nearest ancestor satisfying ancestorEntryTypes is returned.
  • ancestorEntryTypes - The bit-flags specifying entries of which types are to be returned.

$dir.getAncestorInfo(child, n, ancestorEntryTypes)

The same as getAncestor, but returns the ancestor without payload.
  • child - the id of an entry or path starting from which to search for the ancestor.
  • n - how many found ancestors to skip assuming that the search starts from the child entry itself. For example, if n = 0, and the child entry satisfies ancestorEntryTypes filter, than the child entry is returned itself. If, in the same case, n = 1, the nearest ancestor satisfying ancestorEntryTypes is returned.
  • ancestorEntryTypes - the bit-flags specifying entries of which types are to be returned.

$dir.save(parent, entry)

Creates or updates a directory entry.

If the parent is specified as id and an entry with the id doesn't exist, an exception is thrown.

If the entry is being updated (the id of the entry is specified), the parent may be null. In this case the entry is saved under its current parent. If the entry is created, the parent must be specified.

If the entry is being updated (the id of the entry is specified) and the parent specified is not its current one, the entry is moved to the new parent.

If the parent entry already has a child with the same name as the entry being saved, an exception is thrown.
  • parent - the path or id of the parent entry.
  • entry - the entry to be saved.

$dir.move(what, where)

Moves an entry from the current parent to another.

If the entry to be moved doesn't exist, an exception is thrown.

If the parent entry already has a child with the same name as the entry being saved, an exception is thrown.
  • what - the path or id of the entry to move.
  • where - the new parent of the entry.

$dir.remove(what)

Removes an entry.

All descendants are removed with their ancestor.

If the entry to be removed doesn't exist, nothing happens.
  • what - the path or id of the entry to remove.

$dir.exists(what, timestamp)

Checks whether an entry newer than a specified timestamp exists.

Returns true if the specified entry exists and it is newer than the specified timestamp; otherwise, false.
  • what - the path or id of the entry to check.
  • timestamp - the last update timestamp.

Directory entries

The API provides a constructor function for each of directory entry types and DirectoryEntryInfo (the structure containing only common attributes and the type information). Each of the functions can be called without arguments or with a single argument which is the object to use as the prototype for the created one.

Common attributes

  • id: String - the id of the entry.
  • name: String - the name of the entry.
  • createdOn: Date - when the entry was created in the directory. The property is populated if the entry is loaded from the directory; if a client creates or updates an entry, the directory ignores the property.
  • updatedOn: Date - when the entry was updated in the directory last time. The property is populated if the entry is loaded from the directory; if a client creates or updates an entry, the directory ignores the property.
  • acl - access control list of the entry. When the entry is updated, the specified list overwrites the current list in the directory. The access control list is an array of objects with the following attributes:
    • role: String - the role given the permissions.
    • permission: Number - the permissions of the role.

Common methods

  • getType() - returns the type of an entry as one of the directory entry type constants.

DirectoryEntryInfo

The object contains only the common attributes. The getType method will return the type of the corresponding directory entry.

Assembly

The object contains only the common attributes.

Folder

The object contains only the common attributes.

Link

  • target: String - the id of the entry the link is pointing to.

Message

  • data: XmlObject - (optional) the payload of the message.

process

  • workflow: String - the assembly qualified name of the workflow class of the process.

Processor

  • configuration: XmlObject - (optional) Spring.NET IoC container XML configuration containing processor service interface.

Role

  • users: []String - the users assigned the role.

ServicesContainer

  • configuration: XmlObject - Spring.NET IoC container XML configuration containing services definitions.

Set

  • messageType: String - the assembly qualified name of the message type.
  • capacity: Number - the capacity of the set. Zero for unlimited capacity.

State

  • data: XmlObject - the serialized process state.

Workflow

  • definitionType: String - Assembly qualified name of the workflow class.
  • preferredProcessors: []String - Names of the processors which the scheduler will prefer starting the processes of this workflow. If the list is empty, any of the processors will be assigned; if at least one processor is specified as preferred, no other processor will be assigned except the preferred.

File system object

The file system object performs file system operations. It is available via the global variable $fs.

$fs.loadXml(fileName, blobFormat)

Loads XmlObject from a file.
  • fileName - the name of the XML file.
  • blobFormat - the format of the XmlObject BLOB.

$fs.print(fileName, obj, encoding)

Writes an object to a file in a human readable format.

If the file already exists, it will be overwritten.
  • fileName - the name of the target file.
  • obj - the object to write.
  • encoding - the encoding of the target file.

$fs.println(fileName, obj, encoding)

Writes an object to a file in a human readable format appending the new line char to the end.

If the file already exists, it will be overwritten.
  • fileName - the name of the target file.
  • obj - the object to write.
  • encoding - the encoding of the target file.

$fs.fileExists(fileName)

Checks whether a specified file exists.

Returns true if the file exists; otherwise, false.
  • fileName - the name of the file to check.

$fs.directoryExists(fileName)

Checks whether a specified directory exists.

Returns true if the directory exists; otherwise, false.
  • fileName - the name of the directory to check.

$fs.find(path, pattern, deep)

Returns an array of all the file names and directory names that match a search pattern in a specified path, and optionally searches subdirectories.

Returns an array of file system entries that match the search criteria.
  • path - the directory to search.
  • pattern - the string used to search for all files or directories that match its search pattern. The default pattern is for all files and directories: "*".
  • deep - whether to search subdirectories.

$fs.dir(path)

Returns an array of all the file names and directory names in a directory.

Returns an array of all file system entries in the directory.
  • path - the directory to search.

$fs.cd(wd)

Sets the working directory.

Returns the new working directory.
  • wd - the working directory to set.

XML namespaces

The global variable $xmlns contains an object each attribute of which is a mapping of a prefix (the name of the attribute) to an XML namespace (the value). Prefixes defined in $xmlns can be used in the XML constructor functions and XPath queries.

XML functions

xml(xml, format)

Creates an XmlObject from an XML string.
  • xml - XML string.
  • format - the format of the underlying BLOB.

boolToXml(value, format)

Creates an XmlObject message from a boolean value.
  • value - the value to serialize.
  • format - the format of the underlying BLOB.

intToXml(value, format)

Creates an XmlObject message from an integer value.
  • value - the value to serialize.
  • format - the format of the underlying BLOB.

doubleToXml(value, format)

Creates an XmlObject message from a double value.
  • value - the value to serialize.
  • format - the format of the underlying BLOB.

stringToXml(value, format)

Creates an XmlObject message from a string value.
  • value - the value to serialize.
  • format - the format of the underlying BLOB.

XmlObject

A node of an XML document.

xml.xpath(xpath)

Executes an XPath query and returns the result as an array of XmlObject.
  • xpath - the XPath query.

xml.children()

Returns the children of the node as array of XmlObject.

xml.childrenCount()

Returns the number of children of the node.

xml.attr(name, value)

If the value specified is null or undefined, returns the current value of an attribute or undefined if the attribute doesn't exist; otherwise, sets the specified value to the attribute creating it if doesn't exist and returns this.
  • name - the name of the attribute.
  • value - the value to set.

xml.innerText(text)

If the text specified is null or undefined, returns the current inner text of the node; otherwise, sets the specified text as the inner text of the node and returns this.
  • text - the text to set.

xml.append(xml)

Adds a child to the end of the node.
  • xml - the child to add.

xml.prepend(xml)

Adds a child to the beginning of the node.
  • xml - the child to add.

xml.insertBefore(xml, ref)

Inserts a child immediately before a reference node.
  • xml - the child to insert.
  • ref - the reference node.

xml.insertAfter(xml, ref)

Inserts a child immediately after a reference node.
  • xml - the child to insert.
  • ref - the reference node.

xml.remove()

Removes the node from its parent.

xml.asBool()

Deserializes a boolean value from the node.

xml.asInt()

Deserializes an integer value from the node.

xml.asDouble()

Deserializes a double value from the node.

xml.asString()

Deserializes a string value from the node.

Queue object

queue(queuePath)

Creates a queue object.
  • queuePath - path of the queue service client.

queue.getRecipients(start, end)

Returns an array of recipient ids for a given timespan. If the 'start' or 'end' boundary is not specified, the span is unbound from one or both ends.
  • start - a Date object specifying the lower bound of the timespan.
  • end - a Date object specifying the upper bound of the timespan.

queue.getMessagesById(ids)

Returns an array of messages with the given ids.
  • ids - array of strings where each string is an id of a message.

queue.getMessagesByRecipient(recipients, start, end)

Returns an array of messages by given recipient ids and a timespan.
  • recipients - array of strings where each is a recipient id.
  • start - a Date object specifying the lower bound of the timespan.
  • end - a Date object specifying the upper bound of the timespan.

queue.removeMessages(ids)

Removes messages with a given ids.
  • ids - array of strings where each string is an id of a message.

queue.removeRecipients(recipients)

Removes recipients with a given ids.
  • recipients - array of strings where each is a recipient id.

Message objects

The messages are returned as objects with the following attributes:
  • id - string id of a message.
  • recipient - string id of a recipient.
  • putOn - a Date object representing the moment when the message arrived.
  • data - an XML object with the message data.

Processor object

processor(processorName)

Create a processor object by a given processor name.
  • processorName - name of a processor.

processor.start()

Suspends all activities at the processor.

processor.stop()

Resumes all activities at the processor.

Management API

cd(path)

Changes the current working directory and returns the argument. If called without the argument, returns the current working directory.
  • path - the path to set.

globalPath(path)

Transforms a relative path to global.
  • path - the path to transform.

get(what)

Returns a directory entry with payload by its relative path or id.

Returns null if the entry doesn't exist.
  • what - a relative path or id of the entry.

getInfo(what)

Returns a directory entry without payload by its relative path or id.

Returns null if the entry doesn't exist.

what - a relative path or id of the entry.

dir(path, options)

Returns the child entries of an entry specified by its relative path or id.
  • path - the relative path or id of the parent entry.
  • options - an object with the options. The following options are expected.
    • offset(default 0) - how many items to skip from the beginning.
    • max(default 100) - the maximum number of items to return.
    • entryType(default DET_ALL) - the flags indicating entries of which type to return.
    • sortBy(default SORT_DEFAULT) - the sorting order.
    • sort(default ASC) - the sorting direction.
    • withPayload(default false) - whether to return entries with payload.

count(path, entryTypes)

Returns the number of child entries of a specified type of a specified parent.
  • path - the relative path or id of the parent entry.
  • entryTypes(default DET_ALL) - the flags indicating entries of which type to return.

rm(path)

Removes an entry by its relative path or id.
  • path - the relative path or id of the entry to remove.

mkdir(path)

Creates a folder.
  • path - the relative path of the folder to create. All non-existent folders will be created recursively.

rename(path, newName)

Renames an entry specified by an id or path.
  • path - the relative path or id of the entry to rename.
  • newName - the new name of the entry.

exists(path)

Indicated whether an entry with a specified id or path exists.
  • path - the relative path or id of the entry.

grant(options)

Grants permissions on an entry to a role.
  • options - the operation parameters:
    • to - the array of names of the roles which the permission is to be granted.
    • on - the relative path or id of the entry on which the permission is to be granted.
    • permission - the permission to grant.

revoke(options)

Revokes permissions on an entry from a role.
  • options - the operation parameters:
    • from - the array of names of the roles whose the permission is to be revoked.
    • on - the relative path or id of the entry on which the permission is to be revoked.
    • permission - the permission to revoke.

ln(link, target)

Creates a link.
  • link - the relative path of the link to create.
  • target - the relative path or id of the entry for the link to point.

createOrUpdateProcessor(options)

Creates or updates a processor.
  • options - parameters of the operation:
    • name - name of the processor.
    • from - path to a processor endpoint IoC container XML configuration or a JSON object defining the configuration.
    • format(default BLOB_FORMAT_TEXT) - format of the XML configuration BLOB.
    • role(default 'Processor') - name of the processor role.
    • allowSchedulingTo(default ['Application']) - array of the application roles to be allowed to schedule processes for the processor.

changeProcessorPermissions(options)

Changes permissions of an existing processor (overwrites the current permissions).
  • options - parameters of the operation:
    • name - name of the processor.
    • role(default 'Processor') - name of the processor role.
    • allowSchedulingTo(default ['Application']) - array of the application roles to be allowed to schedule processes for the processor.

createOrUpdateRole(options)

Creates or updates a role.
  • options - operation parameters:
    • name - name of the role.
    • users - array of domain user names to be added to the role.

addUsersToRole(role, users)

Adds users to a role specified by its name.
  • role - name of the role.
  • users - array of domain user names to add.

removeUsersFromRole(role, users)

Removes users from a role specified by its name.
  • role - name of the role.
  • users - array of domain user names to remove.

usersOfRole(role)

Returns an array of domain user names of a role.

createOrUpdateServiceContainer(options)

Creates or updates a service container.
  • options - operation parameters:
    • name - the name of the service container (i.e. the part of its path after /Services).
    • from - the name of the XML IoC container configuration file or a JSON object defining the configuration.
    • format(default BLOB_FORMAT_TEXT) - the format of the configuration BLOB.

createOrUpdateSet(options)

Creates or updates a set.
  • options - operation parameters:
    • at - the path of the set.
    • messageType - the assembly qualified name of the message type.

createOrUpdateWorkflow(options)

Creates or updates a workflow.
  • options - operation parameters:
    • name - the name of the workflow (i.e. the part of the path after '/Workflows').
    • definitionType - the assembly qualified name of the workflow definition type. May not be specified for update.
    • preferredProcessors - the array of names of the processors dedicated to execute processes of this workflow. May not be specified.

retryProcess(pid)

Switches a process to the pending state.
  • pid - the id of the process.

retryWaiting(processorName)

Switches all waiting processes to the pending state.
  • processorName (optional) - if specified, only the processes of the specified processor are switched; otherwise, the operation is applied to all processors.

decommissionProcessor(processorName, options)

Prepares a processor for decommission. In particular, it does the following:
  1. Deactivates the processor.
  2. Redistributes (migrates) the processes from 'Pending', 'Running' and 'Waiting' folders to the active processors.
  3. Copies the messages and waiters from the default queues of the processor to the default queues of the corresponding active processors.
  4. Starts the migrated processes.
  • processorName - the name of the processor.
  • options - operation parameters:
    • silent (default false) - if this flag is set, the function will emit no messages.
    • transactionTimeoutSec (default 30) - the timeout (in seconds) of the transactions started by the function.
    • queuesMigrationDelaySec (default 1) - how much long to wait before migrating the default queues. When Flower infers the default queue from a pid, it calculates the path of the process in the directory. It is possible that some senders had calculated the path right before the process is migrated. The message will go to the default queue of the processor being decommissioned. So, there should be delay between the moment when the process itself is migrated and the moment when its messages in the default queue are migrated. The 'queuesMigrationDelaySec' option specifies this delay.
    • reportStatusEverySec (default 1) - how frequently the information messages should be emitted.
    • startMigrated (default true) - whether to start the migrated processes. During the migration, the processes are put to the 'Migrated' folder of the target processor. By default, they are moved to the 'Pending' folder at the last step of decommission, but you may wish not to do that. To start migrated processes manually, call 'startMigratedProcesses'.

startMigratedProcesses()

Starts all migrated processes at all processors.

Debugging

dump(pid, dirName)

Extracts process dump.
  • pid - the id of the process.
  • dirName(default pid) - the directory where the dump should be extracted. If the directory doesn't exist, it is created.

Exceptions

All exceptions thrown from the scripting API and the underlying APIs are transformed to the JavaScript Error so can be caught by the scripts.

Last edited Nov 3, 2013 at 9:39 AM by dbratus, version 5

Comments

No comments yet.