XOG Client Shell, Command Line, Properties File, and SOAP

ccppmop1591
Integrators and system administrators can run XOG commands in the following ways:
2
Video: How to Execute a XOG
The following third-party video is provided by Rego Consulting. This video is provided by CA Technologies “AS IS” and without warranty.

To play this video in full screen, click the YouTube logo to the right of Settings at the bottom of the video. 
Run the XOG from the Command Line
You can enter the parameters that are required to import and export data directly in the command line. You can also store the parameters in a .properties file and call the file from the command line.
Follow these steps:
  1. Open a command prompt:
    • Windows - From the Start menu, select All Programs, CA,
      Classic PPM
      Classic PPM
       XML Open Gateway.
    • UNIX - Navigate to the XOG client home directory.
  2. Type the XOG command with the parameters for the operation that you want to perform and press Enter.
Command-Line Parameters (XOG Client)
The XOG client command line uses the parameters in the following table:
Command
Description
-servername
Indicates the name of the server that is running 
Classic PPM
.
-portnumber
Indicates the port number that is used on the server.
Default:
 80. The typical value for an SSL-enabled server is 443.
-sslenabled
Indicates if the server is an SSL-enabled server.
Default:
 False
-output
Identifies the path to a file where the output of the operation is written. Any existing file is overwritten.
-input
Indicates the path to the file that contains the XOG request.
-username
Indicates the username that is required for the authentication. This user must have
XOG administration
access rights.
-password
Indicates the user password.
-propertyfile
(Optional) The properties file that contains any of the previous parameters.
-fipsenabled
Indicates that the client must operate in a FIPS 140-2 compliant mode. 
Default:
 False
Basic Operations
These XOG commands for basic operations are provided for your reference.
  • To see the command usage, issue this command:
xog -?
  • To read an object through the XOG, issue this command:
xog -servername <host> -portnumber <port> -username <adminuser> -password <password> -input xml/prj_projects_read.xml
  • To write output to a file (instead of displaying it in the console), issue this command:
xog -servername <host> -portnumber <port> -username <adminuser> -password <password> -input xml/prj_projects_read.xml -output xml/prj_project_write.xml
By default, the output is saved to the directory location where you are currently when you run the command.
Run the XOG Using a .Properties File
You can pass the command-line parameters to the XOG client from a .properties file. You can create your own .properties file from the example file that is in the XOG client 
bin
 directory. The advantage of this method is that you can store the parameters for common XOG requests in multiple 
.properties
 files and you can reuse them. This method saves the effort of writing out the parameters on the command line each time that you want to use them. For example, if you are using XOG to import users, companies, resources, and content items, create the following files:
  • users.properties
  • companies.properties
  • resources.properties
  • content.properties
Each file contains different input and output property values that are appropriate for the type of data that you are importing.
Properties File Example
This .properties file example contains the parameters that are required to read project data. The values that are provided for the parameters appear in
bold
.
# --- server host name you want to test against
servername=
localhost
portnumber=
80
#default port number for ssl
#portnumber=
443
#set to true if running against a SSL enabled server
sslenabled=
false
#set to true if running against a SSL enabled server in FIPS 140-2 mode
fipsenabled=
false
output=
out.xml
username=
admin
password=
admin
Create a .Properties File
To create a properties file, make a copy of the example 
test.properties
 file that is located in the 
bin
 directory of the XOG client. Then, modify the copy to import or export specific data that you need. Remember these points as you modify the file:
  • Use the equal sign (=) to assign parameters in the properties file. For example, password=admin.
  • Use the number sign (#) for comments. For example, in the following illustration #portnumber=443 is a comment that will not be read as an input value.
  • The XML input file that is required when you run XOG from the command line must be specified in the .properties file. The list of all the read and write file examples are provided in the 
    xml
     folder are included. Uncomment the file that you want to use for input. Be sure to comment out any files that are not being used as input.
The following image shows the test.properties file with the default parameter values.
This image shows the test.properties file with the default parameter values.
Run the XOG Using the .Properties File
Follow these steps:
  1. Modify the test.properties file or make your own .properties file and save it in the 
    bin
     directory.
  2. Do one of the following:
    • Windows - From the Start menu, select All Programs, CA,
      Classic PPM
      Classic PPM
       
      XML
       
      Open Gateway.
    • UNIX - Navigate to the XOG client home directory.
  3. Issue this command at the XOG prompt: xog -propertyfile test.properties
  4. View the output
Run the XOG Client as a Shell
Typically, the XOG client is used as a non interactive command-line tool. When you develop integrations or test XOG requests, you may want to run the XOG client as a shell. The shell lets you log in once and execute multiple requests before logging out.
Follow these steps:
  1. Open the command prompt:
    • Windows - From the Start menu, select All Programs, CA,
      Classic PPM
      Classic PPM
       XML Open Gateway.
    • UNIX - Navigate to the XOG client home directory.
  2. Issue this command:
    xog
XOG Client Shell Commands
Use the XOG client shell commands when you develop integrations or when you test XOG requests. The XOG client shell uses the commands in the following table:
Command
Description
?
Displays the command usage screen.
login
Retrieves a new session ID by logging in to one of the 
Classic PPM
 servers. The login command string is variable.
Example
:
> login admin/[email protected]:80
logout
 Closes any active sessions.
output
Sets the path and file name where the results of the XOG call are captured.
Example
:
> output c:\xog\xml\out.xml
call
Invokes a XOG request file. The file path may be absolute or relative to the working directory.
Example
:
> call xml/biz_companies_read.xml
> call D:/Integrations/<CAPPM>/write.xml
exit 
 Logs out of active sessions and quits the shell.
Run the XOG Using SOAP
XOG is a web service interface that provides a SOAP API for communication with 
Classic PPM
 over the web. The XOG SOAP API is documented in the WSDL and the XSD files. Any client tool, in addition to the XOG client, can send and receive SOAP messages using the XOG.
These steps describe the general process to invoke XOG directly using SOAP.
Follow these steps:
  1. Call Login to establish a session.
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <Login xmlns="http://www.niku.com/xog"> <Username>admin</Username> <Password>admin</Password> </Login> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
    In this example, the following items are the Login input elements:
    • Login
      The main body element of the login request. Login returns a SessionID that you may use in subsequent requests.
    • Username
      The name of the user doing the work.
    • Password
      The password for the user.
  2. Invoke the request using the SessionID.
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xog="http://www.niku.com/xog"> <SOAP-ENV:Header> <xog:Auth><xog:SessionID>[session id]</xog:SessionID></xog:Auth> </SOAP-ENV:Header> <SOAP-ENV:Body> <obj:WriteChange xmlns:obj="http://www.niku.com/xog/Object"> <NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_change.xsd"> <Header version="12.0.0.5028" externalSource="ORACLE-FINANCIAL"/ <changeRequests> <changeRequest benefits="change request for xog test" code="change request for xog test" description="change request for xog test" impactBaseline="change request for xog test" impactDescription="change request for xog test" name="change request for xog test" ownerCode="admin" priorityCode="LOW" projectCode="riskIssueProject" reasons="change request for xog test" targetResolutionDate="2004-10-15" statusCode="OPEN"> </NikuDataBus> </obj:WriteChange> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
    In this example, the following items are the RequestSessionAL input elements:
    • SessionAL
      The authentication string.
    • NikuDataBus
      The main body element of the Write object request.
      When making multiple requests with the same SessionID such as when an external process wakes up at defined intervals, the SessionID may time out. This is the equivalent of a Logout request. To establish a new SessionID, log in again. The session timeout duration is the same as that set for web browser user sessions; you can configure this setting from the System Options in the Administrator Tool.
  3. Call Logout to invalidate the SessionID and close the session.
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:obj="http://www.niku.com/xog/Object"> <soapenv:Header/> <soapenv:Body> <obj:Logout> <obj:SessionID>[SessionID]</obj:SessionID> </obj:Logout> </soapenv:Body> </soapenv:Envelope>
    In this example, the following items are the Logout input elements:
    • SessionID
      The authentication string that identifies the session to be invalidated.
    • Logout
      The main body element of the Logout request.