Well-Formed Symbolic Script

The first step to make a well-formed script is to add, at the beginning of the script file in a "commented area", a series of tag that will recognize from Symbolic and adapt the application accordingly to the script.



To write your own script you can choose between one of the four supported languages: Groovy, Python, Bash, Perl



The current accepted tag are:

  • @Name: the name for your script. Is used to shown to the users your saved script.
  • @Author: name and references of the script's author.
  • @Type: type of your script. Valid values are: python, groovy, bash, perl
  • @Description: a full description to inform users about what script really does.
Putting just this four simple tags at the beginning of your script, and copying your script in symbolic scripts folder, make Symbolic application able to recognized the script so that users can run it.



XML-RPC Communication

Symbolic exposes a service to which script can connect to get some useful information (like a Symbolic certified machines) and to post execution result.

All "user-runnable" scripts in fact are launched in a way that can we call "asynchronous": Symbolic does not wait the answer from each ran script; so the only way that we can use to communicate the result to Symbolic if calling it through a defined service.

In Symbolic there is an implementation of XML-RPC server that exposes a method to post result from script:postInformation(result). So in your scripts you have to put some lines of code that call XML-RPC server to post the result information.

When Symbolic call a script provides these parameters:



-a: asynchronous execution. Caller will not wait for script answer, so result must be posted through xml-rpc server

-p proccesID: is the Symbolic identification of ran script

-s serverAddress: xml-rpc server address.



For example if you have a python script, symbolic will call it using something like:

python script.py -a -p 10 -s http://localhost:8080/symbolic/api/xmlrpc



So you need to get this parameters inside your script if you want to communicate with Symbolic.



The answer that Symbolic expects must be formatted as dictionary/map with these information:

["process_id":SYMBOLIC_PROC_ID,"status":process_status,"response":some_information]



process_id: is the process id provided during symbolic script invocation.

status: is the result of your script/process (0:Success, 1:Error)

response: what you want. It's better something Human-Readable because will be shown to user without any kind of parsing.



Authentication

The symbolic rpm server is secured behind a password protection. So when you create, inside your script, an instance of xmlrpc client you need to post BasicAuthentication username and password or you will get an "access forbidden error" from Symbolic.

As default setting there is an user that scripts can use to connect to server:

username: externalscript

password: externalscript



Symbolic administrator could change this information or create many other script-enable accounts. These account must have associated a custom script authority (like default created during installation) or root authority (it's better to do not use this authority to make script enable to communicate with symbolic!)