Nodes defined in resources.xml can use editUrl and remoteUrl to specify that the node entry should be edited via some remote URL. The URLs can specify properties about the node to expand prior to being loaded, which allows you to e.g. submit query parameters using the node name.
editUrl - specifies a URL to a standalone remote site which will allow editing of the Node. When specified, the Node resource will display an "Edit" link in the Rundeck GUI and clicking it will open a new browser page for the URL.
remoteUrl - specifies a URL for a remote site which will be loaded in an iframe within a Rundeck page. Clicking the "Edit" link for the Node will load content from the site within the current Rundeck page, allow you to perform your edit at the remote site, and has optional hooks to report the state of the editing process back to the Rundeck page for a more streamlined user interface.
Properties of the Node can be embedded in the URL and expanded prior to use. The syntax is:
${node.property}
Available properties are:
name, hostname, os-name, os-version, os-family, os-arch, username, description, tags, type, project
You can embed these properties within the url like this:
http://mycmdb:8080/node/edit?name=${node.name}
Using the remoteUrl lets you embed another site into an iframe within the Rundeck page, and optionally allows communication back to the Rundeck page about the state of the editing process.
If you want to embed the remote site without having to make any changes to the remote page content, you can do so simply by specifying the remoteUrl to use. When the user clicks "Edit" the site will load within an iframe, and the user can perform whatever actions on the site are necessary. After they are done they will have to manually click the "Close" button on the Rundeck page to close the iframe.
If you want the user interface in Rundeck to be more streamlined, you will have to be able to modify the web pages produced by the remote site to add simple Javascript calls to communicate back to the Rundeck page.
If the remote site implements some Javascript messaging conforming to a simple optional protocol, then the user interface between Rundeck and the remote site can be made more seamless.
Rundeck lets the remote site inform it when the following steps occur:
- The user begins editing a Node
- The user saves the Node changes successfully and is finished
- The user cancels the Node changes, or otherwise has finished without saving
- An error occurs and an error message should be shown.
Due to web browser security restrictions, direct communication between different webpages can only be done through use of the postMessage method.
The remote page can send these messages simply with this javascript:
<script type="text/javascript">
if(window.self!=window.parent){
window.parent.postMessage("...message...","http://rundeckserver:port");
}
</script>
window.parent will be the enclosing browser window when the site is loaded within an iframe. This script simply checks whether the page is loaded in an iframe before sending the message.
The first argument to postMessage is one of the message codes shown below. The second argument is the expected "origin", meaning the URL scheme, server and port of the server receiving the message. You can specify "*" to include any site that may be loading the content, but you may want to restrict it to your Rundeck installation's hostname and port.
Rundeck can receive the following messages sent by the remote site:
rundeck:node:edit:started
~ Sent as soon as the remote edit URL is loaded and indicates that the remote Site understands the messaging protocol and has loaded the correct edit page. You would probably send this on the "edit" or "form" page for the targetted node.
rundeck:node:edit:error or rundeck:node:edit:error:An error message
~ Sent if some error occurs. The remote editing form will close and the error message (if any) will be shown. You would probably send this on the "edit" or "view" page if there is an error locating the targetted Node or loading anything required for the edit process.
The next two messages are only valid after the "started" message has already been received:
rundeck:node:edit:finished:true
~ Sent after the remote form has been saved without errors. This indicates that the editing process is done and has completed with saved changes. You would probably send this on the "view" or "show" page for the targetted node if the save operation was successful.
rundeck:node:edit:finished:false
~ Sent after the remote form has been either cancelled or discarded without changes. This indicates that the editing process is done but no changes were made. You would probably send this on the "view" or "show" for the targetted node (if your site simply shows the node view again) or "list" page (if your site goes back to a list of resources) if the user hits "cancel".
Any message not shown here that is received by Rundeck after it has received the "started" message will be considered unexpected and the editing process will close the iframe.
The user will also have the option to close and cancel the remote editing process at any time.
Note that sending the "error" or "finished" message will close the editing session and all subsequent messages will be ignored.
Here are some examples of using the editUrl and remoteUrl in a resources.xml file:
Specify a simple URL for editing, which will simply produce a link:
<node name="venkman" editUrl="http://mycmdb:8080/node/edit" ... />
Specify a URL for editing, with embedded "name" property as a parameter:
<node name="venkman" editUrl="http://mycmdb:8080/node/edit?name=${node.name}" ... />
Specify a remote URL with embedded "name" and "project" properties as parameters:
<node name="venkman" remoteUrl="http://mycmdb:8080/node/edit?name=${node.name}&project=${node.project}" ... />
Specify a remote URL with embedded "name" property as part of the path:
<node name="venkman" remoteUrl="http://mycmdb:8080/node/edit/${node.name}" ... />