bric_soap - a command-line client for the Bricolage SOAP interface

bric_soap module command [options] [ids or filenames or -]

Modules:

  story
  media
  template
  element
  category
  media_type
  site
  keyword
  user
  desk
  workflow

Commands:

  Asset Commands (story, media, template, element, category,
                  media_type, site, keyword, user, desk):

    list_ids
    export
    create
    update
    delete

  Workflow Commands:

    publish
    deploy
    checkin
    checkout
    move

Options:

  --help                 - shows this screen

  --man                  - shows the full documentation

  --server               - specifies the Bricolage server URL, defaults to
                           the BRICOLAGE_SERVER environment variable if set,
                           http://localhost otherwise.

  --username             - the Bricolage username, defaults to the
                           BRICOLAGE_USERNAME environment variable if
                           set, 'admin' otherwise

  --password             - the password for the Bricolage user.
                           Default to the BRICOLAGE_PASSWORD
                           environment variable if set.

  --with-related-stories - tell export and publish to include related stories

  --with-related-media   - tell export and publish to include related media

  --all                  - synonym for setting --with-related-stories and
                           --with-related-media

  --desk                 - required desk option for move command; optional for
                           create and update commands

  --workflow             - workflow option for move, create, and update commands

  --search field=value   - specify a search for list_ids, field must
                           be a valid search field for the list_ids()
                           method of the appropriate module.

  --verbose              - print a running description to STDERR.  Add
                           a second --verbose and you'll get debugging
                           output too.  Add a third and you'll see a full
                           XML trace.

  --to-preview           - use to_preview option for workflow publish

  --publish-date         - date and time to publish assets for workflow
                           publish. Use format CCYY-MM-DDThh:mm:ssZ, where
                           the "Z" stands for UTC (GMT).

  --published-only       - for workflow publish, republish the published
                           version rather than the current version; if the
                           asset hasn't been published, don't publish anything

  --timeout              - specify the HTTP timeout for SOAP requests in
                           seconds.  Defaults to 30.

  --save-cookie-file     - specify a file to save cookies to for later use-
                           useful if you do not wish to relogin each time.

  --use-cookie-file      - specify a file in which cookies have been saved
                           during a previous session.  If you use this
                           option no username or password are
                           required.

  --chunks               - perform actions in chunks of this many ids.
                           Currently implemented only for the workflow
                           commands (publish, deploy, checkin,
                           checkout, move) but may be expanded to
                           other commands as needed.  Defaults to 0
                           which means no chunking.

  --continue-on-errors   - normally an error returned by a call to the
                           SOAP interface is fatal and bric_soap stops
                           immediately.  If this flag is set then the
                           errror message is printed but processing
                           continues, if possible.  Currently
                           implemented only for the workflow commands
                           (publish, deploy, checkin, checkout, move)
                           but may be expanded to other commands as
                           needed.

Here are some example command-lines. The examples assume that you've set the BRICOLAGE_USERNAME and BRICOLAGE_PASSWORD environment variables and that your local Bricolage server is running on http://localhost. If this is not the case you'll need to add --username, --password and --server arguments as appropriate.

Output an XML dump of the story with story_id 1024 into the file 1024.xml:

  bric_soap story export 1024 > 1024.xml

Upload that story to the server at some.host.org:

  bric_soap story create --server http://some.host.org 1024.xml

A simpler way to do the above two steps:

  bric_soap story export 1024 \
  | bric_soap story create --server some.host.org -

Copy all stories from the local Bricolage to the server at some.host.org:

  bric_soap story list_ids
  | bric_soap story export - \
  | bric_soap story create --server some.host.org -

Delete all stories (gasp!):

  bric_soap story list_ids | bric_soap story delete -

Publish all unpublished stories:

  bric_soap story list_ids --search publish_status=0
  | bric_soap workflow publish -

Publish all unpublished stories at a future time:

  bric_soap story list_ids --search publish_status=0
  | bric_soap workflow publish --publish-date 2005-01-01T00:00:00Z -

Publish all unpublished stories, in chunks of 5 to avoid timeouts

  bric_soap story list_ids --search publish_status=0
  | bric_soap workflow publish --chunks 5 -

Republish all published stories. This is useful when a template change needs to be reflected across a site. The CWsort -k2 -t_ -n is a crude way to make sure that newer stories overwrite older ones.

  bric_soap story list_ids --search publish_status=1 \
  | sort -k2 -t_ -n
  | bric_soap workflow publish -

Copy the story titled Annoying Ad Turns Man Pro-Whaling to the server at some.host.org along with any related media and related stories. Then publish the story along with any related stories or media.

  bric_soap story list_ids \
     --search "title=Annoying Ad Turns Man Pro-Whaling" \
  | bric_soap story export --all - \
  | bric_soap story create --server http://some.host.org - \
  | bric_soap workflow publish --server some.host.org -

Commands that take ids for parameters (delete, export, publish, etc.) always accept fully qualified ids:

  bric_soap workflow publish story_1024 media_1028

Conveniently, this is the format produced by commands that output ids.

Some commands also accept unqualified ids when their meaning is obvious:

  bric_soap story export 1024

If you try to use an unqualified id parameter with a command that requires qualified ids you will receive an error message.

Sam Tregar <stregar@about-inc.com>

Bric::SOAP