Groovy API reference

Troubleshooting and FAQs

3 minute readReferenceTroubleshooting

Troubleshooting

IssueWhat to Do

Get help on the DSL methods

To get the complete list of supported DSL methods, log into ectool, and enter the following command:

ectool evalDsl dsl --describe 1

To get help on a particular DSL method, enter the following command:

ectool evalDsl <dsl_method_name> --describe 1

For example, to get help on the procedure method, enter:

ectool evalDsl procedure --describe 1

Related topics:

The DSL script completes successfully using the evalDsl command; however, the CloudBees CD/RO objects are not created or updated as expected.

Log into ectool, and use the debug option to trace and debug the script processing as follows:

ectool evalDsl "<code_snippet>" --debug 1

For example, to evaluate the project 'TestProj' code snippet, enter:

ectool evalDsl "project 'TestProj'" --debug 1

The debug option generates debug output that you can use to follow the DSL processing and identify issues with the DSL.

To evaluate a DSL file (rather than a code snippet), enter:

ectool evalDsl --dslFile <file_name> --debug 1

For example, to debug a DSL file named TestDsl, enter:

ectool evalDsl --dslFile TestDsl --debug 1

Related topics:

FAQs

  1. I am comfortable with Perl and already use the CloudBees CD/RO Perl API for scripting. Do I need to switch to CloudBees CD/RO DSL?

    DSL is a dynamic scripting language to provide a cleaner and much easier syntax for non-technical users to understand. However, the CloudBees CD/RO Perl API and the REST API are supported as well, and you can continue to use them if they suit your scripting needs.

  2. CloudBees CD/RO DSL is based on Groovy. Are all Groovy constructs available for use in a DSL script?

    Yes, most Groovy constructs, such as closures, named arguments, and others, can be used in your DSL script.

  3. How do I create a DSL script for the CloudBees CD/RO objects that I have created through the UI or using the CloudBees CD/RO Perl API?

    You can use the generateDsl command to create a DSL script for any CloudBees CD/RO object, as shown below.

    ectool generateDsl /projects/Default/applications/MyApp
  4. How do I create or update access control for an object?

    Use one of the following patterns to define access control for objects in your DSL script. These patterns allow the DSL runtime engine to deterministically find the correct CloudBees CD/RO object for creating or updating access control entries (ACEs).

    • Nest access control entries inside the DSL method of the object for which the access control is being defined. For example, the following script provides the user named " joe " full access to project called Foo .

      project 'Foo', {
                aclEntry principalName: 'joe',
                  principalType: 'user',
                  readPrivilege: 'allow',
                  modifyPrivilege: 'allow',
                  changePermissionsPrivilege: 'allow'
      }
    • Use the objectType argument to declare the type of object for which the access control is being defined if the access control method is not enclosed within the DSL method for the object. This can be used to define ACEs for objects such as server and other system objects because they do not have a DSL method similar to other regular objects.

      // Removing any previously set ACL for 'Everyone'
      deleteAclEntry (
           principalType: 'group',
           principalName: 'Everyone',
           objectType : 'server',
           systemObjectName : 'server'
      )
      
      aclEntry principalName: 'joe',
           principalType: 'user',
           objectType : 'server',
           systemObjectName : 'server',
           readPrivilege: 'allow',
           modifyPrivilege: 'allow',
           changePermissionsPrivilege: 'allow'

      or

      aclEntry principalName: 'joe',
          principalType: 'user'
          objectType : 'systemObject',
          systemObjectName : 'resources',
          readPrivilege: 'allow',
          modifyPrivilege: 'allow',
          changePermissionsPrivilege: 'allow'
  5. How do I deal with multibyte characters in DSL files?

    DSL files containing multibyte characters must be encoded in UTF-8 to be CloudBees CD/RO-compatible. DSL files generated by CloudBees CD/RO are in UTF-8 by default, but if you are using a file that was created outside of CloudBees CD/RO, you must ensure that the encoding is in UTF-8.

    Convert the encoding for a DSL file to UTF-8 via a text editor that is capable of doing the conversion, such as Notepad++. To ensure proper encoding you can either:

    • Open the DSL Editor in the CloudBees CD/RO UI and paste in the file’s contents to see if the characters rendered properly (and then use the text editor to make corrections if needed).

    • Run ectool evalDsl --dslFile <filename>.dsl and check the console output for unexpected char errors (and then use the text editor to make corrections if needed).