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.
This feature is only available in Cytoscape 3.6 and up
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 to style the text, make links, and provide formatted code examples. Including clear and explicit instructions using the long description is strongly advised.
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 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.