Adding Custom Build Steps

The Roxy Deployer does a lot of things for you, but sometimes you'll need to do something that the Deployer doesn't handle yet. In that case, you can add a custom step to the deployer, specifying your own XQuery code.

The key is to use the deploy/app_specific.rb file. (You don't need to know Ruby to use this feature.) In this example, a user is adding ODBC views:

class ServerConfig

  def delete_view()
    r = execute_query %Q{
      xquery version "1.0-ml"; 

      import module namespace view = "http://marklogic.com/xdmp/view" 
        at "/MarkLogic/views.xqy";

      try {
        view:remove(
          "main",
          "Compliance"
        )
      } catch ($e) { () }
      (: Deletes a view, of the 'main' schema that contains columns, with a scope on the element, 'html'. :)
    },
    { :db_name => @properties["ml.content-db"] }
  end

  def create_view()
    r = execute_query %Q{
      xquery version "1.0-ml"; 

      import module namespace view = "http://marklogic.com/xdmp/view" 
        at "/MarkLogic/views.xqy";

      try {
        view:schema-create(
          "main",
          ()
        )
      } catch ($e) {()},
      view:create(
          "main",
          "Compliance",
          view:element-view-scope(fn:QName("http://www.w3.org/1999/xhtml","html")),
          ( view:column("uri", cts:uri-reference()), 
            view:column("entityName", cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityName"]/@content',("collation=http://marklogic.com/collation/"))),
            view:column("entityStreetAddress",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityStreetAddress"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("entityCityAddress",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityCityAddress"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("entityCountryAddress",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityCountryAddress"]/@content',("collation=http://marklogic.com/collation//S2", ("nullable")))), 
            view:column("foreignEntityStatus",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "foreignEntityStatus"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("intermediaryEntityStatus",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "intermediaryEntityStatus"]/@content',("collation=http://marklogic.com/collation/codepoint", ("nullable")))),
            view:column("EIN",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "EIN"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("docType", cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "docType"]/@content',("collation=http://marklogic.com/collation//S1", ("nullable"))))
          ),
          () 
      )

      (: Creates a view, of the 'main' schema that contains columns, with a scope on the element, 'html'. :)
    },
    { :db_name => @properties["ml.content-db"] }
  end

end

How To Use It

Custom build steps are implemented using Ruby functions. You can use these steps from the ml script, using the function names:

ml local create_view

Note that these functions are used with an environment.

How It Works

There are three key pieces you need to know to use this feature.

Defining a Function

Before you start editing, the deploy/app_specific.rb file looks like this:

class ServerConfig
  def my_custom_method()
    @logger.info(@properties["ml.content-db"])
  end
end

This is Ruby code. If you don't know Ruby, don't worry, you don't need to. The "class ServerConfig ... end" part of the code is a wrapper that provides some context. We'll focus on defining our custom functions.

This part of the code:

  def my_custom_method()
    ...
  end

defines a Ruby function. You can choose what to call the function, but the name should reflect what step is being done. The example above defined create_view and delete_view. Let's define a simple (but not very useful) function that tells us how many documents are in a database. We can replace my_custom_method(), so we'll start with this:

class ServerConfig
  def get_document_count()
    @logger.info(@properties["ml.content-db"])
  end
end

Note that Ruby, by convention, uses underscores to separate words.

Having declared the function, we need to add some XQuery code. The XQuery gets wrapped in %Q{ }. [TODO]

Specifying the Database Target

[TODO]