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_type
category
media_type
site
keyword
user
desk
workflow
element_type_set  (being removed)
output_channel
contrib_type
dest
pref

Commands:

Asset Commands (story, media, template, element_type, category,
                media_type, site, keyword, user, desk, element_type_set,
                output_channel, contrib_type, dest, pref):

  list_ids
  export
  create  (not 'pref')
  update
  delete  (not 'pref')

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

--without-file         - tell media export to omit the <file> element
                         from the output

--use-related-uri      - tell export to use related_story_uri and
                         related_media_uri instead of related_story_id and
                         related_media_id

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

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

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.

Bash Completion

There is bash tab-completion for bric_soap. See contrib/bash_completion.

Author

Sam Tregar <stregar@about-inc.com>

See Also

Bric::SOAP