Notes for developers

This topics lists some notes for developers of client applications interfacing with the Server Automation REST API.

Guidance for developers creating client applications with the Server Automation REST API. For plans with secure parameters, retrieval preserves Fixlet-defined order for display, but when posting you must reorder the parameter-set so all <parameter> elements precede all <secure-parameter> elements to ensure successful action submission. Advanced parameters can include a list of <parameterData> values to support UI controls such as dropdowns.

Secure Parameters

Some Fixlets make use of the parameter encryption functionality available in the Server Automation application. The SA REST API also offers support to parameter encryption. However one important step must be taken so that taking action on a plan containing secure parameters works.

When the client will request a plan containing Fixlets having secure parameters, the order in which the parameters are returned is the order in which they were originally written in the Fixlet. The reason for this is so that the client can display the parameters in the order with which the Fixlet was designed. This is important to keep this order since it often makes the Fixlet usage more obvious.

However, when the plan is submitted (POSTED) to the REST API, the parameters must be re-ordered so that, within the parameter-set node, the <parameter> tags are all listed first followed by all the <secure-parameter> tags. For example, requesting a plan via a client, we get:

<?xml version="1.0" encoding="UTF-8"?>
<sa-rest xmlns="http://iemfsa.tivoli.ibm.com/REST" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <execute-plan action-name="SimpleEncrypt" prefetch="false">
        <step sequence="1" name="CustomTaskWithRichParamsModified-encrypt-6">
            <parameter-set>
                    <parameter name="choice" title="Pick One:" label="Go on ! Pick One!" ui-type="Select" value-type="specified" >
                        <parameterData>Maybe</parameterData>
                        <parameterData>Yes</parameterData>
                        <parameterData>No</parameterData>
                    </parameter>
                <parameter name="FileName" >C:\\messages.txt</parameter>
                <parameter name="Message" >Hello World!</parameter>
                <secure-parameter name="passwordTest" title="Password" label="Test password for encryption" ui-type="textbox" sub-ui-type="password" ></secure-parameter>
                <secure-parameter name="passwordTest2" title="Another Password" label="Test password for encryption 2" ui-type="textbox" sub-ui-type="password" ></secure-parameter>
                <parameter name="passwordTest3" title="Another Password" label="Test password for encryption 3" ui-type="textbox" sub-ui-type="password" ></parameter>
                <parameter name="passwordTest4" title="Another Password" label="Test password for encryption 4" ui-type="textbox" sub-ui-type="password" ></parameter>
            </parameter-set>
            <target-set>
                <computer name="TPMTEST-10" id="3009075" />
            </target-set>
        </step>
        <schedule>
            <HasStartTime>false</HasStartTime>
            <StartDateTimeOffset>P0DT0H0M0S</StartDateTimeOffset>
            <HasEndTime>false</HasEndTime>
            <EndDateTimeOffset>P2DT0H0M0S</EndDateTimeOffset>
            <UseUTCTime>true</UseUTCTime>
        </schedule>
    </execute-plan>
</sa-rest>

To post this plan to take action on it, we need to modify the XML structure as follows:

<?xml version="1.0" encoding="UTF-8"?>
<sa-rest xmlns="http://iemfsa.tivoli.ibm.com/REST" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <execute-plan action-name="SimpleEncrypt" prefetch="false">
        <step sequence="1" name="CustomTaskWithRichParamsModified-encrypt-6">
        <parameter-set>
            <parameter name="choice" title="Pick One:" label="Go on ! Pick One!" ui-type="Select" value-type="specified" >Yes
                <parameterData>Maybe</parameterData>
                <parameterData>Yes</parameterData>
                <parameterData>No</parameterData>
            </parameter>
            <parameter name="FileName" >C:\\messages.txt</parameter>
            <parameter name="Message" >Hello World posted!</parameter>
            <parameter name="passwordTest3" title="Another Password" label="Test password for encryption 3" ui-type="textbox" sub-ui-type="password" >clear text</parameter>
            <parameter name="passwordTest4" title="Another Password" label="Test password for encryption 4" ui-type="textbox" sub-ui-type="password" >clear text 2</parameter>
            <secure-parameter name="passwordTest" title="Password" label="Test password for encryption" ui-type="textbox" sub-ui-type="password" >secure text</secure-parameter>
            <secure-parameter name="passwordTest2" title="Another Password" label="Test password for encryption 2" ui-type="textbox" sub-ui-type="password" >secure text 2</secure-parameter>
        </parameter-set>
        <target-set>
            <computer name="TPMTEST-10" id="3009075" />
        </target-set>
        </step>
        <schedule>
            <HasStartTime>false</HasStartTime>
            <StartDateTimeOffset>P0DT0H0M0S</StartDateTimeOffset>
            <HasEndTime>false</HasEndTime>
            <EndDateTimeOffset>P2DT0H0M0S</EndDateTimeOffset>
            <UseUTCTime>true</UseUTCTime>
        </schedule>
    </execute-plan>
</sa-rest>

Advanced parameters

In a user interface, standard parameters only require a regular text input widget. Advanced parameters however, may require a drop down or list type of widget. In this case the <parameter> tag will contain a list of <parameterData> tags representing the list of valid values to be used for the parameter.

The following example shows a plan with one Fixlet containing a parameter with 3 potential values:

<?xml version="1.0" encoding="UTF-8"?>
<sa-rest xmlns="http://iemfsa.tivoli.ibm.com/REST" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <execute-plan action-name="SimpleEncrypt" prefetch="false">
        <step sequence="1" name="CustomTaskWithRichParamsModified-encrypt-6">
            <parameter-set>
                <parameter name="choice" title="Pick One:" label="Go on ! Pick One!" ui-type="Select" value-type="specified" >
                    <parameterData>Maybe</parameterData>
                    <parameterData>Yes</parameterData>
                    <parameterData>No</parameterData>
                </parameter>
                <parameter name="FileName" >C:\\messages.txt</parameter>
                <parameter name="Message" >Hello World!</parameter>
                <secure-parameter name="passwordTest" title="Password" label="Test password for encryption" ui-type="textbox" sub-ui-type="password" ></secure-parameter>
                <secure-parameter name="passwordTest2" title="Another Password" label="Test password for encryption 2" ui-type="textbox" sub-ui-type="password" ></secure-parameter>
                <parameter name="passwordTest3" title="Another Password" label="Test password for encryption 3" ui-type="textbox" sub-ui-type="password" ></parameter>
                <parameter name="passwordTest4" title="Another Password" label="Test password for encryption 4" ui-type="textbox" sub-ui-type="password" ></parameter>
            </parameter-set>
            <target-set>
                <computer name="TPMTEST-10" id="3009075" />
            </target-set>
        </step>
        <schedule>
            <HasStartTime>false</HasStartTime>
            <StartDateTimeOffset>P0DT0H0M0S</StartDateTimeOffset>
            <HasEndTime>false</HasEndTime>
            <EndDateTimeOffset>P2DT0H0M0S</EndDateTimeOffset>
            <UseUTCTime>true</UseUTCTime>
        </schedule>
    </execute-plan>
</sa-rest>