# 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.<br /><br />To write your own script you can choose between one of the four supported languages: <span style="font-weight: bold;">Groovy</span>, <span style="font-weight: bold;">Python</span>, <span style="font-weight: bold;">Bash</span>, <span style="font-weight: bold;">Perl</span><br /><br />The current accepted tag are:<br /><ul><li><span style="font-style: italic;">@Name</span>: the name for your script. Is used to shown to the users your saved script.</li><li><span style="font-style: italic;">@Author</span>: name and references of the script's author.</li><li><span style="font-style: italic;">@Type</span>: type of your script. Valid values are: python, groovy, bash, perl</li><li><span style="font-style: italic;">@Description</span>: a full description to inform users about what script really does.</li></ul>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.<br /><br /><span style="font-weight: bold;">XML-RPC Communication</span><br />Symbolic exposes a service to which script can connect to get some useful information (like a Symbolic certified machines) and to post execution result.<br />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.<br />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.<br />When Symbolic call a script provides these parameters:<br /><br /><span style="font-style: italic;">-a</span>: asynchronous execution. Caller will not wait for script answer, so result must be posted through xml-rpc server<br /><span style="font-style: italic;">-p proccesID</span>: is the Symbolic identification of ran script<br /><span style="font-style: italic;">-s serverAddress</span>: xml-rpc server address.<br /><br />For example if you have a python script, symbolic will call it using something like:<br /><pre><code>python script.py -a -p 10 -s http://localhost:8080/symbolic/api/xmlrpc<br /></code></pre><br />So you need to get this parameters inside your script if you want to communicate with Symbolic.<br /><br />The answer that Symbolic expects must be formatted as dictionary/map with these information:<br /><pre><code>["process_id":SYMBOLIC_PROC_ID,"status":process_status,"response":some_information]<br /></code></pre><br /><span style="font-style: italic;">process_id</span>: is the process id provided during symbolic script invocation.<br /><span style="font-style: italic;">status</span>: is the result of your script/process (0:Success, 1:Error)<br /><span style="font-style: italic;">response</span>: what you want. It's better something Human-Readable because will be shown to user without any kind of parsing.<br /><br /><span style="font-weight: bold;">Authentication</span><br />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.<br />As default setting there is an user that scripts can use to connect to server:<br /><pre><code>username: externalscript<br />password: externalscript<br /></code></pre><br />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!)