App Developers: Cytoscape Command Best Practices
When developing apps that enable automation, observing best practices in coding and design can greatly improve the accessibility of that automation, its interaction with other apps and services, and aid in tracing any errors during testing and in runtime.
This page documents best practices for app developers who are enabling automation features as Cytoscape Commands, and assumes some familiarity with adding commands.
To determine whether you should expose automation features as Commands, Functions or both, consult the automation summary page.
For best practices relating to Cytoscape Functions, see Cytoscape Function Best Practices for and Swagger Best Practices.
The namespace you choose for your command via the ServiceProperties.COMMAND_NAMESPACE property should succinctly and uniquely describe its place among all other commands. For example, all layout commands are registered with the layout namespace.
When creating a task that contains Tunables, it is important to be aware of the context field in the Tunable annotation.
@Tunable (description="Example Input Parameter", context=Tunable.BOTH_CONTEXT)The above code snippet specifies that the Tunable field is intended for inclusion in both the Cytoscape GUI and in the Cytoscape Command Line. Options exist for Tunables that are in the GUI only (Tunable.GUI_CONTEXT) and non-GUI (Tunable.NOGUI_CONTEXT). It is important that no Tunables required for the execution of the Task via automation are of the Tunable.GUI_CONTEXT type.
Several fields and parameters exist to provide users with documentation about Commands. This documentation becomes available in both the Command Line, accessible through via Tools --> Command Line Dialog in the Cytoscape menu bar, and in the CyREST Command API Swagger, accessible through via Help --> Automation --> CyREST Command API in the Cytoscape menu bar.
The ServiceProperties.COMMAND_DESCRIPTION property is set when a service is registered, and can be seen in the code snippet below:
String returnAValueDescription = "Add two numbers (a and b) and return their value using ObservableTask.";
Properties returnAValueTaskFactoryProperties = new Properties();
...
returnAValueTaskFactoryProperties.setProperty(COMMAND_DESCRIPTION, returnAValueDescription);
...
TaskFactory returnAValueTaskFactory = new ReturnAValueTaskFactory();
registerAllServices(bc, returnAValueTaskFactory, returnAValueTaskFactoryProperties);The command description can then be seen in two locations: the Command Line Dialog and the Swagger UI.
Since the space allotted to this description is limited in both cases, any text in a description should be kept informative, but brief.
The Tunable description field can be set for any Tunable annotation to provide a brief description. An example implementation can be seen in the code snippet below:
@Tunable (description="Value A")
public Double a = 0.1;Tunable descriptions can then be seen in two documentation locations: the Command Line Dialog and the Swagger UI.
Since the space allotted to this description is limited in both cases, any text in a description should be kept informative, but brief.
Additionally, if the context of the Tunable is BOTH, the description will appear in the dialog for the relevant Command.
The appearance of the description in Cytoscape dialogs, Command Line Help, and Swagger UI should always be considered when writing descriptions, and should be easily understandable in every context.
These features are only available in Cytoscape 3.6 and up, and use the CyREST develop branch. See the TaskFactory JSON Result Sample for details on these dependencies
As of Cytoscape 3.6, Commands are capable of providing JSON results via CyREST. Using JSON allows complex data to be made available outside of Cytoscape via Commands, and their use enables richer documentation through Swagger. Implementing JSON output is highly recommended for every command.
The TaskFactory JSON Result Sample provides an example of how to implement JSON Results for a Command.
When a JSON Command is executed, the JSON Results for each Task in that Command are included as a list in the data field of a CIResponse JSON object. The results of a simple query to a JSON Command are shown below:
{
"data": {
"results": [
{
"name": "Hodor",
"values": [
1,
2,
3
]
}
]
},
"errors": []
}Details about the CIResponse model can be found in the CIResponse Section of the Cytoscape Function Best Practices wiki page.
If a Task throws an Exception, that exception will be translated into a CIError, which will be included in the errors field of a CIResponse. An example of a thrown error within a CIResponse is shown below:
{
"data": {
"results": []
},
"errors": [
{
"status": 500,
"type": "urn:cytoscape:ci:cyrest-core:v1:handle-json-command:errors:2",
"message": "Error processing arguments: Couldn't parse value from: string for setting: taxonID",
"link": "file:/Users/davidotasek/CytoscapeConfiguration/3/framework-cytoscape.log"
}
]
}The message field of the CIError is generated from the message field of the Java Exception thrown. To make common errors easier for automation scripters to handle, errors thrown from Tasks should be built using concise and specific messages describing the error.
Details about the enclosing CIError model can be found in the CIError Section of the Cytoscape Function Best Practices wiki page.
The ServiceProperties.COMMAND_LONG_DESCRIPTION property is set when a service is registered, and can be seen in the code snippet below:
String returnAValueLongDescription = "Returns a JSON Object containing a ```name``` and a ```values``` field. The ```name``` field is set by the request message body. The ```values``` field is preset.";
...
returnAValueTaskFactoryProperties.setProperty(COMMAND_LONG_DESCRIPTION, returnAValueLongDescription);The command long description can then be seen in the Implementation Notes section of the Swagger UI.
The space allotted to a long description is large, and the description text supports the use of Markdown, which can be used for styling, making links, and providing formatted code examples. Including clear and explicit instructions using the long description is strongly advised.
The Tunable long description field can be set for any Tunable annotation to provide a more detailed description. An example implementation can be seen in the code snippet below:
@Tunable (description="Name", longDescription="The value to return in the result's name field")
public String name = "";Tunable descriptions can then be seen in Data Type section in the Swagger UI.
Long description text supports the use of Markdown, which can be used for styling, making links, and providing formatted code examples. Including clear and explicit instructions using the long description is strongly advised.