Administrator API

Use the Administrator API
Examples

You can use the Administrator API to perform most ColdFusion Administrator tasks programmatically. The Administrator API consists of a set of ColdFusion components (CFCs) that contain methods you call to perform Administrator tasks. For example, you use the setMSQL method of datasource.cfc to add a SQL Server data source.

The CFCs for the Administrator API are located in the cf_web_root/CFIDE/adminapi directory. Each CFC corresponds to an area of the ColdFusion Administrator, as the following table shows:

CFC	Description
accessmanager.cfc	Specify the user name, password, description, access rights, sandboxes, and allowed roles for individual users.
administrator.cfc	Contains basic Administrator functionality, including login, logout, the Migration wizard, and the Setup wizard. You must call the `login` method before calling any other methods in the Administrator API.
base.cfc	Base object for all other Administrator API CFCs.
datasource.cfc	Add, modify, and delete ColdFusion data sources.
debugging.cfc	Manage debug settings
eventgateway.cfc	Manage event gateways
extensions.cfc	Manage custom tags, mappings, CFXs, applets, CORBA, and web services.
office.cfc	Manage OpenOffice settings.
mail.cfc	Manage ColdFusion mail settings.
runtime.cfc	Manage runtime settings for fonts, cache, charts, configuration, and other settings.
security.cfc	Manage passwords, RDS, and sandbox security.
serverinstance.cfc	Start, stop, and restart Tomcat servers. This CFC only works when running the multiserver configuration.
servermonitoring.cfc	Perform many of the Server Monitor tasks programmatically.

The adminapi directory also contains an Application.cfm file and two subdirectories.

Note: If you are using sandbox security, enable access to the cf_web_root/CFIDE/adminapi directory to use the Administrator API.

Following are the styles of methods in the Administrator API:

Method arguments: When setting complex or varied values, the Administrator API uses method arguments.
Getting and setting simple values: When setting simple values, such as true or false debug settings, the Administrator API uses get and set property methods.
To view the methods, method arguments, and documentation for the Administrator API CFCs, use the CFC Explorer. For example, to view datasource.cfc when running in the server configuration, open a browser to http://localhost:8500/CFIDE/adminapi/datasource.cfc.

Use the Administrator API

Instantiate administrator.cfc:
```
<cfscript> 
    // Login is always required. 
    adminObj = createObject("component","cfide.adminapi.administrator");
```
Note: You can instantiate administrator.cfc and call the login method in a single line of code, as the following example shows:
```
createObject("component","cfide.adminapi.administrator").login("admin");
```
Note: You can log in as a user other than administrator, but with proper permissions, as follows. Provide the user name after the password.
```
createObject("component","cfide.adminapi.administrator").login("#password#","#username#")
```
Call the administrator.cfc login method, passing the ColdFusion Administrator password or the RDS password:
```
adminObj.login("admin");
```

Instantiate the desired CFC:

myObj = createObject("component","cfide.adminapi.debugging");

Call the desired CFC method (this example enables debugging):

myObj.setDebugProperty(propertyName="enableDebug", propertyValue="true");

Examples

The following example adds a SQL Server data source:

<cfscript> 
    // Login is always required. This example uses two lines of code. 
    adminObj = createObject("component","cfide.adminapi.administrator"); 
    adminObj.login("admin"); 
 
    // Instantiate the data source object. 
    myObj = createObject("component","cfide.adminapi.datasource"); 
 
    // Create a DSN. 
    myObj.setMSSQL(driver="MSSQLServer",  
        name="northwind_MSSQL",  
        host = "xx.x.xxx.xx",  
        port = "1433", 
        database = "northwind", 
        username = "sa", 
        login_timeout = "29", 
        timeout = "23", 
        interval = 6, 
        buffer = "64000", 
        blob_buffer = "64000", 
        setStringParameterAsUnicode = "false", 
        description = "Northwind SQL Server", 
        pooling = true, 
        maxpooledstatements = 999, 
        enableMaxConnections = "true", 
        maxConnections = "299", 
        disable_clob = true, 
        disable_blob = true, 
        disable = false, 
        storedProc = true, 
        alter = false, 
        grant = true, 
        select = true, 
        update = true, 
        create = true, 
        delete = true, 
        drop = false, 
        revoke = false ); 
</cfscript>

The following example adds the same SQL Server data source, but uses the argumentCollection attribute to pass all method arguments in a structure:

<cfscript> 
    // Login is always required. This example uses a single line of code. 
    createObject("component","cfide.adminapi.administrator").login("admin"); 
 
    // Instantiate the data source object. 
    myObj = createObject("component","cfide.adminapi.datasource"); 
 
    // Required arguments for a data source. 
    stDSN = structNew(); 
    stDSN.driver = "MSSQLServer"; 
    stDSN.name="northwind_MSSQL"; 
    stDSN.host = "xx.x.xxx.xx"; 
    stDSN.port = "1433"; 
    stDSN.database = "northwind"; 
    stDSN.username = "sa"; 
 
    // Optional and advanced arguments. 
    stDSN.login_timeout = "29"; 
    stDSN.timeout = "23"; 
    stDSN.interval = 6; 
    stDSN.buffer = "64000"; 
    stDSN.blob_buffer = "64000"; 
    stDSN.setStringParameterAsUnicode = "false"; 
    stDSN.description = "Northwind SQL Server"; 
    stDSN.pooling = true; 
    stDSN.maxpooledstatements = 999; 
    stDSN.enableMaxConnections = "true"; 
    stDSN.maxConnections = "299"; 
    stDSN.enable_clob = true; 
    stDSN.enable_blob = true; 
    stDSN.disable = false; 
    stDSN.storedProc = true; 
    stDSN.alter = false; 
    stDSN.grant = true; 
    stDSN.select = true; 
    stDSN.update = true; 
    stDSN.create = true; 
    stDSN.delete = true; 
    stDSN.drop = false; 
    stDSN.revoke = false; 
 
    //Create a DSN. 
    myObj.setMSSQL(argumentCollection=stDSN); 
</cfscript> 
<!--- Optionally dump the stDSN structure. ---> 
<!---  
<cfoutput> 
<cfdump var="#stDSN#"> 
</cfoutput> 
--->