bric_soap - a command-line client for the Bricolage SOAP interface
bric_soap module command [options] [ids or filenames or -]
story media template element category media_type site keyword user desk workflow
Asset Commands (story, media, template, element, category, media_type, site, keyword, user, desk):
list_ids export create update delete
publish deploy checkin checkout move
--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
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 -
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 <firstname.lastname@example.org>
the Bric::SOAP manpage