The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Cisco UCS Director Orchestrator offers a list of well-defined input types for custom tasks. Cisco UCS Director also enables you to create a customized workflow input for a custom workflow task. You can create a new input type by cloning and modifying an existing input type.
Before writing custom tasks, you must meet the following prerequisites:
Cisco UCS Director is installed and running on your system. For more information about how to install Cisco UCS Director, refer to the Cisco UCS Director Installation and Configuration Guide.
You have a login with administrator privileges. You must use this login when you create and modify custom tasks.
You can create a custom input for a custom workflow task. The input is displayed in the list of input types that you can map to custom task inputs when you create a custom workflow task.
You can use an existing custom workflow input in Cisco UCS Director to create a custom workflow input.
A custom workflow input must be available in Cisco UCS Director.
To create a custom task, do the following:
When you create a custom task, rather than typing in the custom task code into the script window or cutting and pasting code from your favorite editor, you can import the code from a file stored in a Git repository. To do this, you:
Create one or more text files in a Git repository, either in public Github or your own private enterprise Git repository.
Register the repository in Cisco UCS Director.
Select the repository and specify the text file that contains the custom task script.
To Register the repository in Cisco UCS Director, see Adding a Git Repository in UCS Director.
To select the repository and text file, see Downloading Custom Task Script Code Using Git.
To register a Git repository in Cisco UCS Director, do the following:
Create a Git repository. The repository can be on any Git server, public or private that is accessible from your Cisco UCS Director. Check-in one or more files containing JavaScript code for your custom tasks into your repository
Step 1 | Choose . | ||
Step 2 | On the Integration page, click Manage Repositories. | ||
Step 3 | Click Add. | ||
Step 4 | On the Add Repository page, complete the required fields, including the following:
| ||
Step 5 | When you are satisfied that the repository information is correct, click Submit. |
To create a new custom task by importing text from a Git repository, do the following:
Create a Git repository and check-in one or more text files containing the JavaScript code for your custom tasks into your repository.
Add the Git repository to Cisco UCS Director. See Adding a Git Repository in UCS Director.
Step 1 | On the Orchestration page, click Custom Workflow Tasks. | ||
Step 2 | Click Add. | ||
Step 3 | Complete the required fields on the Custom Task Information page. See Creating a Custom Task. | ||
Step 4 | Complete the required fields on the Custom Task Inputs page. See Creating a Custom Task. | ||
Step 5 | Complete the required fields on the Custom Task Outputs page. See Creating a Custom Task. | ||
Step 6 | Complete the required fields on the Controller page. See Creating a Custom Task. | ||
Step 7 | On the Script page, complete the required fields: | ||
Step 8 | To save the custom task, click Submit.
|
You can use the new custom task in a workflow.
To import artifacts into Cisco UCS Director, do the following:
Step 1 | Choose Orchestration. | ||||||||||||||||
Step 2 | On the Orchestration page, click Workflows. | ||||||||||||||||
Step 3 | Click Import. | ||||||||||||||||
Step 4 | On the Import screen, click Select a File. | ||||||||||||||||
Step 5 | On the Choose File to Upload screen, choose the file to be imported. Cisco UCS Director import and export files have a .wfdx file extension. | ||||||||||||||||
Step 6 | Click Open. When the file is uploaded, the File Upload screen displays File ready for use. | ||||||||||||||||
Step 7 | Click Next. The Import screen displays a list of Cisco UCS Director objects contained in the uploaded file. | ||||||||||||||||
Step 8 | (Optional) Specify how objects are handled if they duplicate names already in the workflow folder. On the Import screen, complete the following fields:
| ||||||||||||||||
Step 9 | Click Import. |
Step 1 | Choose Orchestration. | ||||||||
Step 2 | On the Orchestration page, click Workflows. | ||||||||
Step 3 | Click Export. | ||||||||
Step 4 | On the Select Workflows screen, choose the workflows that you want to export. | ||||||||
Step 5 | Click Next. | ||||||||
Step 6 | On the Select Custom Tasks screen, choose the custom tasks that you want to export. | ||||||||
Step 7 | Click Next. | ||||||||
Step 8 | On the Export: Select Script Modules screen, choose the script modules that you want to export. | ||||||||
Step 9 | Click Next. | ||||||||
Step 10 | On the Export: Select Activities screen, choose the activities that you want to export. | ||||||||
Step 11 | Click Next. | ||||||||
Step 12 | On the Export: Confirmation screen, complete the following fields:
| ||||||||
Step 13 | Click Export. |
You are prompted to save the file.
You can clone tasks in the task library to use in creating custom tasks. You can also clone a custom task to create a custom task.
The cloned task is a framework with the same task inputs and outputs as the original task. However, the cloned task is a framework only. This means that you must write all the functionality for the new task in CloupiaScript.
Note also that selection values for list inputs, such as dropdown lists and lists of values, are carried over to the cloned task only if the list values are not system-dependent. Such things as names and IP addresses of existing systems are system-dependent; such things as configuration options supported by Cisco UCS Director are not. For example, user groups, cloud names, and port groups are system-dependent; user roles, cloud types, and port group types are not.
Step 1 | Choose Orchestration. |
Step 2 | Click Custom Workflow Tasks. |
Step 3 | Click Clone From Task Library. |
Step 4 | On the Clone from Task Library screen, check the row with the task that you want to clone. |
Step 5 | Click Select. A custom workflow task is created from the task library. The new custom task is the last custom task in the Custom Workflow Tasks report. The new custom task is named after the cloned task, with the date appended. |
Step 6 | Click Submit. |
Edit the custom workflow task to ensure that the proper name and description are in place for the cloned task.
You can use an existing custom workflow task in Cisco UCS Director to create a custom workflow task.
A custom workflow task must be available in Cisco UCS Director.
Step 1 | Choose Orchestration. |
Step 2 | Click Custom Workflow Tasks. |
Step 3 | Click the row with the custom workflow task that you want to clone. The Clone icon appears at the top of the custom workflow tasks table. |
Step 4 | Click Clone. |
Step 5 | On the Clone Custom Workflow Task screen, update the required fields. |
Step 6 | Click Next. The inputs defined for the custom workflow tasks appear. |
Step 7 | Click the row with the task input that you want to edit and click Edit to edit the task inputs. |
Step 8 | Click Add to add a task input entry. |
Step 9 | Click Next. Edit the task outputs. |
Step 10 | Click Add to add a new output entry. |
Step 11 | Click Next. |
Step 12 | Edit the controller scripts. See Controlling Custom Workflow Task Inputs. |
Step 13 | Click Next. |
Step 14 | To customize the custom task, edit the task script. |
Step 15 | Click Submit. |
You can modify the appearance and behavior of custom task inputs using the controller interface available in Cisco UCS Director.
Use controllers in the following scenarios:
To implement complex show and hide GUI behavior including finer control of lists of values, tabular lists of values, and other input controls displayed to the user.
To implement complex user input validation logic.
With input controllers you can do the following:
Show or hide GUI controls: You can dynamically show or hide various GUI fields such as checkboxes, text boxes, drop-down lists, and buttons, based on conditions. For example, if a user selects UCSM from a drop-down list, you can prompt for user credentials for Cisco UCS Manager or change the list of values (LOVs) in the drop-down list to shown only available ports on a server.
Form field validation: You can validate the data entered by a user when creating or editing workflows in the Workflow Designer. For invalid data entered by the user, errors can be shown. The user input data can be altered before it is persisted in the database or before it is persisted to a device.
Dynamically retrieve a list of values: You can dynamically fetch a list of values from Cisco UCS Director objects and use them to populate GUI form objects.
Controllers are always associated with a form in the Workflow Designer's task inputs interface. There is a one-to-one mapping between a form and a controller. Controllers work in two stages, marshalling and unmarshalling. Both stages have two substages, before and after. To use a controller, you marshall (control UI form fields) and/or unmarshall (validate user inputs) the related GUI form objects using the controller's scripts.
The following table summarizes these stages.
Stage |
Sub-stage |
---|---|
Marshalling — Used to hide and unhide form fields and for advanced control of LOVs and tabular LOVs. |
beforeMarshall — Used to add or set an input field and dynamically create and set the LOV on a page (form). afterMarshall — Used to hide or unhide an input field. |
Unmarshalling - Used for form user input validation. |
beforeUnmarshall — Used to convert an input value from one form to another form, for example, to encrypt the password before sending it to the database. afterUnmarshall — Used to validate a user input and set the error message on the page. |
Controllers do not require any additional packages to be imported.
You do not pass parameters to the controller methods. Instead, the Cisco UCS Director framework makes the following parameters available for use in marshalling and unmarshalling:
Parameter |
Description |
Example |
---|---|---|
Page |
The page or form that contains all the task inputs. You can use this parameter to do the following: |
page.setHidden(id + ".portList", true); page.setValue(id + ".status", "No Port is up. Port List is Hidden"); |
id |
The unique identifier of the form input field. An id is generated by the framework and can be used with the form input field name. |
page.setValue(id + ".status", "No Port is up. Port List is Hidden");// here ‘status’ is the name of the input field. |
Pojo |
POJO (plain old Java object) is a Java bean representing an input form. Every GUI page must have a corresponding POJO holding the values from the form. The POJO is used to persist the values to the database or to send the values to an external device. |
pojo.setLunSize(asciiValue); //set the value of the input field 'lunSize' |
See Example: Using Controllers for a working code sample that demonstrates the controller functionality.
The following code example demonstrates how to implement the controller functionality in custom workflow tasks using the various methods — beforeMarshall, afterMarshall, beforeUnmarshall and afterUnmarshall.
/* Method Descriptions: Before Marshall: Use this method to add or set an input field and dynamically create and set the LOV on a page(form). After Marshall: Use this method to hide or unhide an input field. Before UnMarshall: Use this method to convert an input value from one form to another form, for example, when you want to encrypt the password before sending it to the database. After UnMarshall: Use this method to validate a user input and set the error message on the page. */ //Before Marshall: /* Use the beforeMarshall method when there is a change in the input field or to dynamically create LOVs and to set the new input field on the form before it gets loaded. In the example below, a new input field 'portList' is added on the page before the form is displayed in a browser. */ importPackage(com.cloupia.model.cIM); importPackage(java.util); importPackage(java.lang); var portList = new ArrayList(); var lovLabel = "eth0"; var lovValue = "eth0"; var portListLOV = new Array(); portListLOV[0] = new FormLOVPair(lovLabel, lovValue);//create the lov input field //the parameter 'page' is used to set the input field on the form page.setEmbeddedLOVs(id + ".portList", portListLOV);// set the input field on the form ============================================================================================================= //After Marshall : /* Use this method to hide or unhide an input field. */ page.setHidden(id + ".portList", true); //hide the input field 'portList'. page.setValue(id + ".status", "No Port is up. Port List is Hidden"); page.setEditable(id + ".status", false); ============================================================================================================= //Before Unmarshall : /* Use the beforeUnMarshall method to read the user input and convert it to another form before inserting into the database. For example, you can read the password and store the password in the database after converting it into base64 encoding, or read the employee name and convert to the employee Id when the employee name is sent to the database. In the code example below the lun size is read and converted into an ASCII value. */ importPackage(org.apache.log4j); importPackage(java.lang); importPackage(java.util); var size = page.getValue(id + ".lunSize"); var logger = Logger.getLogger("my logger"); if(size != null){ logger.info("Size value "+size); if((new java.lang.String(size)).matches("\\d+")){ var byteValue = size.getBytes("US-ASCII"); //convert the lun size and get the ASCII character array var asciiValueBuilder = new StringBuilder(); for (var i = 0; i < byteValue.length; i++) { asciiValueBuilder.append(byteValue[i]); } var asciiValue = asciiValueBuilder.toString()+" - Ascii value" //id + ".lunSize" is the identifier of the input field page.setValue(id + ".lunSize",asciiValue); //the parameter 'page' is used to set the value on the input field . pojo.setLunSize(asciiValue); //set the value on the pojo. This pojo will be send to DB or external device. } } ============================================================================================================= // After unMarshall : /* Use this method to validate and set an error message. */ importPackage(org.apache.log4j); importPackage(java.lang); importPackage(java.util); //var size = pojo.getLunSize(); var size = page.getValue(id + ".lunSize"); var logger = Logger.getLogger("my logger"); logger.info("Size value "+size); if (size > 50) { //validate the size page.setError(id+".lunSize", "LUN Size can not be more than 50MB "); //set the error message on the page page.setPageMessage("LUN Size can not be more than 50MB"); //page.setPageStatus(2); }
You can use the output of a previous task as an input for an another task in a workflow directly from the script of a custom task and an Execute Cloupia Script task of the task library.
To access this output, you can use one of the following ways:
Retrieve the variable from the workflow context using the getInput() method.
Refer to the output using system variable notation.
To retrieve an output using the context getInput() method, use:
var name = ctxt.getInput("PreviousTaskName.outputFieldName");
For example:
var name = ctxt.getInput("custom_task1_1684.NAME"); // NAME is the name of the task1 output field that you want to access
To retrieve an output using system variable notation, use:
var name = "${PreviousTaskName.outputFieldName}";
For example:
var name = "${custom_task1_1684.NAME}"; // NAME is the name of the task1 output field that you want to access
Step 1 | Choose Orchestration. |
Step 2 | Click Custom Workflow Tasks. |
Step 3 | Click Add and key in the custom task information. |
Step 4 | Click Next. |
Step 5 | Click + and add the input details. |
Step 6 | Click Submit. |
Step 7 | Click Next. The Custom Task Outputs screen is displayed. |
Step 8 | Click + and add the output details for the custom task. |
Step 9 | Click Next. The Controller screen is displayed. |
Step 10 | Click + and add the controller details for the custom task. |
Step 11 | Click Next. The Script screen is displayed. |
Step 12 | Select
JavaScript as the execution language and enter the following script to execute.
logger.addInfo("Hello World!"); logger.addInfo("Message "+input.message);where message is the input field name. |
Step 13 | Click Save Script. |
Step 14 | Click Submit. The custom task is defined and added to the custom tasks list. |
Step 15 | On the Orchestration page, click Workflows. |
Step 16 | Click Add to define a workflow, and define the workflow inputs and outputs. Once the workflow inputs and outputs are defined, use the Workflow Designer to add a workflow task to the workflow. |
Step 17 | Double-click a workflow to open the workflow in the Workflow Designer screen. |
Step 18 | On the left side of the Workflow Designer, expand the folders and choose a custom task (for example, 'Hello world custom task'). |
Step 19 | Drag and drop the chosen task to the workflow designer. |
Step 20 | Complete the fields in the Add Task (<Task Name>) screen. |
Step 21 | Connect the task to the workflow. See Cisco UCS Director Orchstration Guide. |
Step 22 | Click Validate workflow. |
Step 23 | Click Execute Now and click Submit. |
Step 24 | See the log messages in the Service Request log window. |