NAME

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

SYNOPSIS

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

Modules:

Story
Media
Template
Element
Workflow

Commands:

Asset Commands (Story, Media, Template, Element, Category):

  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

--workflow             - workflow option for move command

--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

--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.

EXAMPLES

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, 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 reflected across a site. The sort -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 -

ID PARAMETERS

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.

AUTHOR

Sam Tregar <stregar@about-inc.com>

SEE ALSO

Bric::SOAP