Artificer Command Line
----------------------
#Using the Artificer cmdline tool `s-ramp.sh`#

In the `bin` directory of the distribution you can find the `s-ramp.sh`. Run this command to fire up the shell
....
./artificer.sh
....
The shell supports auto-completion and keeps a command history for duration of the session.

Connecting to Artificer server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To connect the shell to the server type `connect` and hit the tab key. It should auto-complete
to say `connect http://localhost:8080/artificer-server` and when hitting the return key
you will be prompted for user credentials.  If everything is successful, the cursor should go 
from red to green.  Of course you will need to update the server and port information if your 
Artificer repository runs elsewhere.


Browsing the Artificer repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To browse the artifacts in the repository run the following query:
....
artificer> query /s-ramp
Querying the S-RAMP repository:
    /s-ramp
Atom Feed (9 entries)
  Idx                    Type Name
  ---                    ---- ----
    1           ImageDocument user-properties.png
    2                Document overlord.demo.CheckDeployment-taskform.flt
    3         BrmsPkgDocument SRAMPPackage.pkg
    4           ImageDocument overlord.demo.SimpleReleaseProcess-image.png
    5           ImageDocument run-build-install.png
    6                Document overlord.demo.SimpleReleaseProcess-taskform.flt
    7           ImageDocument audio-input-microphone-3.png
    8            BpmnDocument overlord.demo.SimpleReleaseProcess.bpmn 
    9            TextDocument HttpClientWorkDefinitions.wid
....
To obtain the metaData of `overlord.demo.SimpleReleaseProcess.bpmn`, which is number 8 in the list, issue
....
artificer> getMetaData --feed 8
Meta Data for: 31b3acbc-cda8-4856-9e34-d3e645283035
--------------
  -- Core S-RAMP Info --
  Type: BpmnDocument
  Model: ext
  UUID: 31b3acbc-cda8-4856-9e34-d3e645283035
  Name: overlord.demo.SimpleReleaseProcess.bpmn
  Derived: false
  Created By: <anonymous>
  Created On: 2013-03-08T14:00:37.036-05:00
  Modified By: <anonymous>
  Modified On: 2013-03-18T14:58:46.328-04:00
artificer> 
....

Updating artifact MetaData
~~~~~~~~~~~~~~~~~~~~~~~~~~

Properties
^^^^^^^^^^
To update a property on the artifact use `property set` and hit the `tab` key
....
artificer> property set
description       name           version 
....
this shows a list of properties that can be updated. To add a description to this artifact use
....
artificer> property set description "BPMN2 artifact representing the SimpleReleaseProcess"
Successfully set property description.
artificer> updateMetaData
Successfully updated artifact overlord.demo.SimpleReleaseProcess.bpmn.
....
To verify issue
....
artificer> getMetaData --feed 8
Meta Data for: 31b3acbc-cda8-4856-9e34-d3e645283035
--------------
  -- Core S-RAMP Info --
  Type: BpmnDocument
  Model: ext
  UUID: 31b3acbc-cda8-4856-9e34-d3e645283035
  Name: overlord.demo.SimpleReleaseProcess.bpmn
  Derived: false
  Created By: <anonymous>
  Created On: 2013-03-08T14:00:37.036-05:00
  Modified By: <anonymous>
  Modified On: 2013-03-18T16:09:56.879-04:00
  -- Description --
BPMN2 artifact representing the SimpleReleaseProcess
....
and you can see the added description at the bottom of the printout.

Custom Properties
^^^^^^^^^^^^^^^^^
To add a `custom property` called `kurt` with value `stam` you can run
....
artificer> property set kurt stam
Successfully set property kurt.
artificer> updateMetaData
Successfully updated artifact overlord.demo.SimpleReleaseProcess.bpmn.
....
and to verify that the `custom property` was added issue
....
artificer> getMetaData --feed 8
Meta Data for: 31b3acbc-cda8-4856-9e34-d3e645283035
--------------
  -- Core S-RAMP Info --
  Type: BpmnDocument
  Model: ext
  UUID: 31b3acbc-cda8-4856-9e34-d3e645283035
  Name: overlord.demo.SimpleReleaseProcess.bpmn
  Derived: false
  Created By: <anonymous>
  Created On: 2013-03-08T14:00:37.036-05:00
  Modified By: <anonymous>
  Modified On: 2013-03-18T16:21:16.119-04:00
  -- Description --
BPMN2 artifact representing the SimpleReleaseProcess
  -- Custom Properties --
  kurt: stam
artificer> 
....
When hitting the `tab` key on `property set` results in
....
artificer> property set
description    kurt           name           version 
....
which now had the added `custom property` `kurt`.

Classifications
^^^^^^^^^^^^^^^
To add a `classification` of `deployment-status` to your artifact use
....
artificer> classification add "http://www.jboss.org/overlord/deployment-status.owl#Dev"
Successfully added classification 'http://www.jboss.org/overlord/deployment-status.owl#Dev'.
artificer> updateMetaData
Successfully updated artifact overlord.demo.SimpleReleaseProcess.bpmn.
....
and to verify that it was added
....
artificer> getMetaData --feed 8
Meta Data for: 31b3acbc-cda8-4856-9e34-d3e645283035
--------------
  -- Core S-RAMP Info --
  Type: BpmnDocument
  Model: ext
  UUID: 31b3acbc-cda8-4856-9e34-d3e645283035
  Name: overlord.demo.SimpleReleaseProcess.bpmn
  Derived: false
  Created By: <anonymous>
  Created On: 2013-03-08T14:00:37.036-05:00
  Modified By: <anonymous>
  Modified On: 2013-03-18T16:30:42.641-04:00
  -- Description --
BPMN2 artifact representing the SimpleReleaseProcess
  -- Classifications --
  Classified By: http://www.jboss.org/overlord/deployment-status.owl#Dev
  -- Custom Properties --
  kurt: stam
artificer>
....

Querying the Artificer Repository using XPath2 Syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
S-RAMP supports an XPath2 Syntax for querying. For example to obtain all WSDL models in the repository use
....
artificer> query /s-ramp/wsdl/WsdlDocument
Querying the S-RAMP repository:
    /s-ramp/wsdl/WsdlDocument
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1            WsdlDocument OrderService.wsdl                       
artificer> 
....
When this WSDL file was uploaded `derived` information was extracted from it and stored a WSDL model. TO see the various data structures it derived simply hit the tab on `query /s-ramp/wsdl`
....
artificer> query /s-ramp/wsdl/
Binding                  BindingOperation         BindingOperationFault    BindingOperationInput    BindingOperationOutput   
Fault                    Message                  Operation                OperationInput           OperationOutput          
Part                     Port                     PortType                 WsdlDocument             WsdlExtension            
WsdlService              
artificer> 
....
Note that derived data is `read only`, and cannot be updated by the user. 

To obtain all Operations in this WSDL use
....
query /s-ramp/wsdl/Operation
Querying the S-RAMP repository:
    /s-ramp/wsdl/Operation
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1               Operation submitOrder
artificer> 
....

You can narrow this query down even more by adding that the name needs to start with `submit`
....
query "/s-ramp/wsdl/Operation[xp2:matches(@name, 'submit.*')]"
Querying the S-RAMP repository:
    /s-ramp/wsdl/Operation[xp2:matches(@name, 'submit.*')]
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1               Operation submitOrder                             
artificer> 
....
don't forget to use the surrounding quotes, and a `.` after `submit` as required by XPath2.

To obtain all the artifacts that were derived from an artifact you can use
....
/s-ramp[relatedDocument[@uuid = '<uuid>'
....
In this case we use the uuid of a wsdl and get all the artifacts derived from the wsdl
....
query "/s-ramp[relatedDocument[@uuid = '15a94308-a088-4a03-ad83-e60239af74e4']]"
Querying the S-RAMP repository:
	/s-ramp[relatedDocument[@uuid = '15a94308-a088-4a03-ad83-e60239af74e4']]
Atom Feed (16 entries)
  Idx                    Type Name
  ---                    ---- ----
    1          OperationInput submitOrder                             
    2             WsdlService OrderService                            
    3             SoapAddress soap:address                            
    4   BindingOperationInput wsdl:input                              
    5             SoapBinding soap:binding                            
    6                    Part parameters                              
    7                 Binding OrderServiceBinding                     
    8  BindingOperationOutput wsdl:output                             
    9                 Message submitOrderResponse                     
   10         OperationOutput submitOrderResponse                     
   11        BindingOperation submitOrder                             
   12                 Message submitOrder                             
   13               Operation submitOrder                             
   14                    Port OrderServicePort                        
   15                    Part parameters                              
   16                PortType OrderService  
....

To get a list of all artifacts that were extracted from another archive use
....
query "/s-ramp[expandedFromDocument[@uuid = '<uuid>']"
....
let's say we uploaded a jar file containing switchyard artifacts, with uddi '67c6f2d3-0f10-4f0d-ada6-d85f92f02a33':
....
query "/s-ramp[expandedFromDocument[@uuid = '67c6f2d3-0f10-4f0d-ada6-d85f92f02a33']]"
Querying the S-RAMP repository:
	/s-ramp[expandedFromDocument[@uuid = '67c6f2d3-0f10-4f0d-ada6-d85f92f02a33']]
Atom Feed (3 entries)
  Idx                    Type Name
  ---                    ---- ----
    1             XmlDocument switchyard.xml                          
    2             XmlDocument beans.xml                                                        
    3             XmlDocument faces-config.xml                         
....

For more information about querying the repository see the 'S-RAMP Query Language' section 
of this guide.

Stored Queries
^^^^^^^^^^^^^^^
The above queries can also be executed using Stored Queries:
....
artificer> createStoredQuery FooQuery /s-ramp/ext/FooType
artificer> executeStoredQuery FooQuery
Querying the S-RAMP repository:
    /s-ramp/ext/FooType
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1                 FooType FooArtifact
....

Running Commands in Batch
~~~~~~~~~~~~~~~~~~~~~~~~~
An interesting thing you can do with the Artificer CLI is to use it as a batch processor.
To do this, simply create a text file with all of the commands you wish to run in a
batch (one per line) and then ask the Artificer CLI to execute the batch.  For example,
a batch of commands may look like this:

----
# Connect to Artificer
connect http://localhost:8080/artificer-server admin admin123!

# Upload an ontology
ontology:upload /path/to/data/my-ontology.owl

# Add some artifact content
upload /path/to/artifact-content.ext
property set property-foo Bar
updateMetaData
----

To execute the batch, simply do:

----
artificer.sh -f /path/to/cli-commands.txt
----

Batch File Property Interpolation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that it is possible to use Ant style property replacements within your
Artificer CLI batch file.  The CLI will look for property values as System 
Properties, or by passing in the path to a Java Properties file to the CLI
via a "-propertiesFile" option.

We support simply property replacement as well as property replacement with
defaults.  For example:

----
# Connect to Artificer
connect ${artificer.endpoint:http://localhost:8080/artificer-server} ${artificer.username:admin} ${artificer.password:admin123!}
upload ${resource.path}
----

The above batch file allows whoever is using it (via the Artificer CLI) to set 
the following properties either via System Properties or via a passed-in 
properties file:

* resource.path - (required)
* artificer.endpoint - (optional, defaults to http://localhost:8080/artificer-server)
* artificer.username - (optional, defaults to admin)
* artificer.password - (optional, defaults to admin123!)

Log-to-File
~~~~~~~~~~~
Rather than creating batch files by hand, the Artificer CLI includes a "log-to-file" option.  All commands executed during the CLI session will be logged to a file, directly usable as a batch file in the future.

----
artificer.sh -l /path/to/cli-commands.txt
----
