API error messages
Introduction
IntroductionAccess tokenACLApplication dependencyApplicationApplication tierArchive connectorArtifactCatalogChange historyCI buildCI build detailCI configurationCI eventCI jobClusterComponentsCredentialCredential providerCustom filterDashboardDashboard columnDatabase configurationData retention policyDeployer applicationDevOps Insight data sourceDirectory providerDynamic environmentEmail configurationEmail notifierEnvironmentEnvironment tierGatewayGroupInstalling or upgrading remote agentsJobKerberos keytabMicroserviceMicroservice mappingMiscellaneousObjectObject tagsParameterPersonaPipelinePluginPlugin configurationPlugin catalogProcedureProcessProcess dependencyProcess stepProjectPropertyReleaseReportReporting filterReport object associationReport object attributeReport object typeResourceRolling deployScheduleSCM syncServerServer settings categoryService accounts for webhooksSessionSingle sign-on for OpenID ConnectSingle sign-on for SAMLSnapshotsTier mapTriggerUserUser emailUtility resourceWait dependencyWebhook resultWidgetWidget filter overrideWorkflowWorkflow definitionWork itemsWorkspaceZone
Perl API response and element glossary
Introduction
Examples
Troubleshooting
IntroductionaccesstokenaclaclentryactualparameterapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitionstringresulttagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseraccesstokenuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Generating DSL Scripts

3 minute readReferenceDeveloper productivity

There are three ways to generate DSL scripts, based on your needs:

Single objects

Via UI

You can export any object such as a pipeline, application, microservice, environment, or release to a DSL file. This file can then be stored in the source code repository of your choice. This DSL-based representation of an object lets you recreate the state of the object.

To export an object into DSL:

  1. Select DSL Export from the object’s three-line menu. The Export DSL screen displays.

    IDE editor
    Figure 1. Export DSL

  2. Select export options.

    DSL format

    Select a language format for DSL export. Choices are:

    • Groovy

    • YAML DSL format is a Preview feature.

      A Preview feature:

      • Has not undergone end-to-end testing with CloudBees products

      • Is provided without service-level agreements (SLA) and therefore does not include CloudBees' commitment on functionality or performance

      • May impact other stable areas of the product when used

      • May have limited documentation

      • May not be feature complete during the Preview period

      • May graduate from preview state to fully supported or be removed from the product

      • May introduce incompatible, backward-breaking changes that could revoke the ability to upgrade

      Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

    Suppress Nulls

    Select to suppress both object and custom properties with null values in the exported DSL. If not selected, all properties are returned, subject to the Suppress Defaults setting.

    To override null values for custom properties from being suppressed, set the server setting, disableNotSuppressNullsOption, to true:

    ectool setProperty /server/settings/disableNotSuppressNullsOption true
    ▼

    Suppress Parent

    Select to exclude the object’s parent references in the exported DSL.

    Suppress Defaults

    Select to suppress object and custom properties with default values in the exported DSL.

    Include ACLs

    Select to include each object’s access control list in the exported DSL.

    Options for child objects

    These options control how the hierarchy is stored in the file structure.

    Suppress children

    Select to exclude fields with child values in the exported DSL.

  3. Select Export to initiate the DSL export. The DSL file is downloaded to your local system.

  4. Commit this version of the DSL file into your source code repository.

This DSL file has all the details of the pipeline stages, gates, and tasks. It also retains references to the snapshots used for deployments in various stages of this pipeline.

Snapshots capture references to the exact versions of the artifacts, configurations, and so on. This lets you recreate the exact state of the pipeline at any point in the future for various scenarios. To recreate a pipeline, you check out that DSL file and evaluate the DSL using either the evalDsl API or the DSL editors. Evaluating this DSL recreates the pipeline as it was when the DSL file was created.

While this example showcases pipeline objects, the DSL export functionality is available from most CloudBees CD/RO objects.

This method is limited to the following object types: Applications, microservices, environments, master components, environment and resource templates, reports, releases, and pipelines.

Via API

Use the ectool generateDsl <path> [optionals] API command to generate an XML file representing the contents of a CloudBees CD/RO object. See the generateDsl command for full syntax and examples.

Object Hierarchy

Via UI

To generate DSL scripts representing the contents of an entire CloudBees CD/RO object structure including all nested objects, parameters, and custom properties, use the export DSL catalog item available with the CloudBees CD/RO UI. This method is available for all CloudBees CD/RO object types.

The scripts are organized in a file structure suitable for importing back into the object structure. In this way, you can use the corresponding Import DSL service catalog item to easily create new objects based on the existing object structure or to override the original object structure.

Getting started with DSL
DSL automation as code