Use API Plug-ins to Load Data into Policies and Forms

This article contains the following topics:
casm173
This article contains the following topics:
Administrators and service designers work together to write API plug-ins that dynamically load data into policies and forms, as follows:
  • For a policy, this data specifies the assignees (approvers) for a request. You use the plug-in instead of specifying assignees manually using the Action Builder. When a user submits a request, the API plug-in dynamically specifies the assignees.
  • For a form, this data specifies the value for any of the following fields: dynamic tables, dual lists, or select boxes and their options. For example, when a user completes a form to reserve a virtual computer, the report data object populates the list of available computers. You can also write other report data objects to populate related fields, for example, options for RAM and disk space.
API plug-ins query the MDB or another data source. The API plug-in returns the number of objects that meet the criteria that you specify. You can either write your own API plug-ins or copy and modify the predefined plug-ins to meet your requirements. In both cases, you meet the prerequisites and compile your plug-ins
before
you can use them.
API plug-ins are deployed as jar files in the plugins directory of the filestore. API plug-ins run in the same Java Virtual Machine instance as CA Service Catalog.
Perform the tasks that apply:
Use API Plug-ins for Policies
To write and use an API plug-in for policies, follow this process:
  1. Define the purpose or goal of the plug-in.
    An API plug-in is useful when you query an external system for data to specify the assignees. An API plug-in is also useful when the identities vary according to the data in the request. Based on this data, the plug-in dynamically creates the assignee list and specifies the assignee levels.
  2. Meet the prerequisites:
  3. Be able to do the following proficiently:
    • Program in Java.
    • Create policies, including conditions, and understand the types of assignees required.
  4. Review the API Plug-in documentation, as follows:
    1. Select Administration, Tools, Plug-ins.
    2. Click API Documentation.
    3. Review the com.ca.usm.plugins.apis.policies package.
    The API documentation is automatically generated Java documentation from the Java class methods for the plug-ins. You use the interfaces, classes, methods, and so on, to implement your plug-in.
  5. Download and review the sample API plug-in for policies, as follows:
    1. Select Administration, Tools, Plug-ins.
    2. Click the Sample Policy Plug-in, review the details, and download the source code.
    3. Open and review the SamplePolicyPlugin.java file in the \src\java\com\ca\usm\plugins\samples\policy folder. Use this sample policy plug-in as a model.
  6. Create a Java class that implements the interface, com.ca.usm.plugins.apis.policies.AssignmentPolicyPlugin. The sample policy plug-in illustrates how to implement this interface.
  7. (Optional) If you use content configuration forms, retrieve values from the fields on these forms. Use the forms as needed.
  8. Create a properties file for the plug-in. You can use the plugin.properties file in the sample policy plug-in as a model for your properties files.
  9. Create a folder to store the properties file and any JAR files that provide the classes and supporting libraries.
    Store the properties file at the
    top
    level of the folder. Do
    not
    store the properties file in a subfolder.
  10. Activate the plug-in:
    1. Stop the CA Service Catalog Windows service.
    2. Copy your folder (including all subfolders, if any) to the USM_HOME\filestore\plugins folder.
  11. Start the CA Service Catalog Windows service.
  12. Verify that the plug-in was successfully adopted:
    1. Select Administration, Tools, Plug-ins.
    2. Verify that the plug-in is listed and that its details appear properly.
  13. Test this plug-in:
    1. Use it to specify assignees for a policy.
    2. Submit a request that activates the policy and verify that the policy assigns approvers dynamically as intended.
Use API Plug-ins for Forms
To write and use an API plug-in for use in a form, follow this process:
  1. Define the purpose of the plug-in. For example, to populate a select field with meeting rooms that a user can reserve for a specified time period. Other examples include options for the meeting room, such as projectors, video conferencing units, and microphones.
  2. Meet the prerequisites. Be able to do the following proficiently:
    • Program in Java.
    • Create forms using the Form Designer.
    • Create the following fields in Form Designer forms:
      • Single select, multi-select, and dual list fields
      • Dynamic table fields
  3. Review the API Plug-in documentation, as follows:
    1. Log in to CA Service Catalog and select Administration, Tools.
    2. Select Links.
    3. Click Plug-in Documentation.
    The API documentation is automatically generated Java documentation from the Java class methods for the plug-ins. You use the interfaces, classes, methods, and so on, to implement your plug-in.
  4. Create a Java class for the type of Form Designer field for which the plug-in applies, as follows:
    • For single select, multiselect, and dual list fields: Create a Java class that implements the com.ca.usm.plugins.apis.forms.FDSelectDataProvider interface. A sample implementation of this interface is provided in the Sample Select Plug-in, with id ca.catalog.samples.select-plugin.
    • For dynamic table fields: Create a Java class that implements the com.ca.usm.plugins.apis.forms.FDTableDataProvider interface. A sample implementation of this interface is provided in the Sample Table Plug-in, with id ca.catalog.samples.table-plugin.
    To access Java documentation for the interfaces, click Administration, Tools, Plug-ins, and click API Documentation.
    To download sample source code, click the sample plug-ins on the same page and click Download Source Code.
  5. Create a properties file for the plug-in, as follows:
    • Use the sample plug-ins as models for your properties files. In that case, change the plug-in id property in the plugin.properties file.
    • Use the Java Development Kit 1.6 (or higher) and Apache Ant 1.8 (or higher) to use the included build file to compile the plug-in.
    • Use a private classloader for your plug-ins. To use a private classloader, add the following line to your plugin.properties file:
      classloader.type=private
      Custom plug-ins from CA Service Catalog Release 12.7 do
      not
      require any updates after you upgrade CA Service Catalog. These plug-ins continue to function as they originally did.
  6. (Optional) If you use content configuration forms, retrieve values from the fields on these forms. Use the forms as needed.
  7. Perform the actions that apply:
    • Configure Pagination Parameters for Select Fields.
    • Configure Attributes for Select Boxes Only.
    • Configure Sorting and Pagination Parameters for Dynamic Tables.
  8. Create a folder to store the properties file and any JAR files that provide the classes and supporting libraries.
    Store the properties file at the
    top
    level of the folder. Do
    not
    store the properties file in a subfolder.
  9. Activate the plug-in:
    1. Copy your folder (including all subfolders, if any) to the plugins folder of the filestore.
    2. Select Administration, Tools, Plug-ins, and click the Reload Plugins method.
  10. Verify that the plug-in was successfully adopted:
    1. Log in to CA Service Catalog and select Administration, Tools.
    2. Select Plug-ins.
    3. Verify that the plug-in is listed and that its details appear properly.
You are ready to test this API for use in a form field.
Configure Pagination Parameters for Select Fields
Your plug-in can return a large amount of data in a select field on a form. In that case, you often specify the page size of the results in the select field. An example is displaying ten results per page in the select field. To accomplish this task, configure the parameters for pagination in the related Java class and object.
Follow these steps:
  1. Edit the Java class that implements the interface, com.ca.usm.plugins.apis.forms.FDSelectDataProvider. Implement the following method in FDSelectDataProvider:
    List<FDOption> getOptions(int start, int numToReturn);
    • start
      Specifies the first row to return. This parameter is an integer.
    • numToReturn
      Specifies the number of rows to return. This parameter is an integer.
    This method returns a list of FDOption objects:
      • The key value pair (id and value) in a report data object for the options of the select field.
      • Data that complement the key value pair. You can optionally display this additional data in other fields (except the select field) on the form.
    The value of the _id attribute of each field must match the one of the keys in the additional data.
  2. Also in FDSelectDataProvider, implement the following method:
    int totalCount();
    This method returns the total number of rows that exist.
For more information and examples, see the API plug-in documentation.
Configure Attributes for Select Boxes Only
Some HTML Attributes apply to select boxes only. For more information, see the Attributes for Select Boxes Only section.
Configure Sorting and Pagination Parameters for Dynamic Tables
Your plug-in can return a large amount of data in a dynamic table in a form. In such a scenario, you specify the page size of the results. An example is displaying ten results per page on the form. Similarly, you often want to let users sort the results on each page in ascending or descending order. To accomplish both tasks, configure the parameters for sorting and pagination in the related Java class and object.
Follow these steps:
  1. Click Catalog, Forms, and open the form of interest.
  2. Open the table and verify that the attribute named Sortable is set to True.
    If this attribute is enabled (True), then users can click arrows on the table column headers to sort the results.
  3. Edit the Java class that implements the interface, com.ca.usm.plugins.apis.forms.FDTableDataProvider. Implement the following method in FDTableDataProvider:
    List<FDTableRow> getTableRows(int start, int numToReturn, String sortField, boolean sortAscending);
    Users determine these values by interacting with the form, for example, by clicking to view the next page.
    • start
      Specifies the first row to return. This parameter is an integer.
    • numToReturn
      Specifies the number of rows to return. This parameter is an integer.
    • sortField
      Specifies the rows to sort. When the value is null, no sorting occurs. This parameter is a string.
    • sortAscending
      Specifies whether to sort the results in ascending or descending order. This parameter is Boolean.
    This method returns FDTableRow objects, which are described in a later step.
  4. Also in FDTableDataProvider, implement the following method:
    int totalCount();
    This method returns the total number of rows that exist.
  5. Use the FDTableRow object and its methods to return table row data. You can use the following methods:
    • public void setColumnValue(String columnId, String data)
      Specifies the following to set the value for a column:
      • String columnid - Specifies “_id” attribute of a component of a table.
      • String data - Specifies a value that you can parse and place into the field on the table.
    • public String getColumnValue(String columnId)
      Specifies the matching GET function for the previous SET function (public void setColumnValue).
    • public Set getColumns()
      Returns the set of column IDs stored in this object.
For more information and examples, see the API plug-in documentation.