The ColdFusion Administrator is an extremely powerful and easy-to-use Web-based interface for managing your ColdFusion environment. It provides scores of pages to configure data sources, server settings, Web services, logging and debugging, and more.

Pretty much any aspect of your ColdFusion server can be controlled and configured by the administrator. That's a great feature of ColdFusion, but it does present some problems.

In developing ColdFusion MX 7, we contemplated the challenges associated with providing a single way to administer the server and, as a result, decided to introduce a new feature, the ColdFusion Admin API, which allows you to perform most ColdFusion MX administrator tasks programmatically.

A common complaint about the Web-based administrator is that there is only one password required to access all the functionality of the Admin and, once in, you can perform many different types of tasks. Some are developer tasks: adding data sources, toggling debugging on and off, monitoring log files, and so on. Some are security-related tasks such as setting passwords and creating and modifying security sandboxes. Others are administrative tasks such as configuring mail servers, Verity, and server mappings. In most companies, these different tasks fall to different individuals. For example, a developer who needs to add a new access data source should likely not be permitted to change the admin password for the whole server! And do you want to grant full administrative permission to a developer just to allow him or her to turn on debugging for a project?

Another problem with the Web-based administrator is that developers could not incorporate any administrative tasks into the context of their applications. Perhaps you make a change to the signature of a Web service and need to "refresh" the Web service stubs created by the server. Or you need to clear the trusted cache if a certain event occurs in your application. Unfortunately, any administrative task required a human administrator, which made these kinds of programmatic implementations impossible.

The ColdFusion Administrator API solves these issues by giving developers the ability to perform most of the tasks that are possible in the Web-based administrator in their CFML code. The Administrator API consists of a set of ColdFusion components (CFCs) that contain methods you call to perform administrator tasks. For example, use the setMSQL method of datasource.cfc to add a SQL Server data source. So let's see how the Admin API could offer a solution to some of the problems mentioned above. See Figure 1.

The Admin API allows you to create custom administrator applications. If you want a couple of developers to be able to add new data sources and nothing else, you can create a simple form-based interface that calls the data source cfc. This would also allow you to build in additional security and logging to these functions. For example, you can see which developer logged in at what time and what data sources were added.

The Admin API is also used in the ColdFusion MX 7 Extensions for Dreamweaver to enable the new debugging functionality. Prior to the availability of these extensions, you were required to enter a developer's IP address from the ColdFusion administrator to allow debugging output to be used from his or her machine. Now, the extensions make a call to the Admin API to handle this automatically. It sends a request to the ColdFusion server, asking it to enable debug mode for the current workstation's IP only, then it sends the actual page request and retrieves the results. After the request has been completed and all desired data retrieved, it sends another call asking to disable the debug mode for the current IP.

Since the Admin API is called from regular CFML code, any of the functions that it exposes can be called from any CF page. For example, the situation mentioned above for Web services could be solved with this simple code:

<cfinvoke
  component="CFIDE.adminapi.extensions"
  method="reloadWebService">
   <cfinvokeargument name="name" value=""/>
   <cfinvokeargument name="path" value=""/>
</cfinvoke>

The Admin API is broken out across several components:
The easiest way to find out all of the different functions in each is to use the CFC panel in Dreamweaver. Select CF Components from the dropdown at the top of the components tab of the application panel. Scroll down to find the CFIDE.adminapi package and expand. Each component listed above can be expanded showing all of the functions, their required parameters, and so forth.

The addition of the Administrator API to ColdFusion MX 7 allows developers to solve some key limitations of the Web-based ColdFusion administrator. You can create flexible, custom "mini-Administrators" to grant only certain abilities to certain developers; script administrative functionality into a ColdFusion application; and much more. Best of all, the API is a core, supported feature of the product: you'll never again need to worry about tinkering with the service factory or other "undocumented" approaches to programmatic administrator access.