Aurora_Gaimon

CA PPM: XOG - SOAP client tool (Part 1)

Blog Post created by Aurora_Gaimon Employee on Apr 3, 2017

I like to change topics and I think it's time to talk about different SOAP client tools. Indeed, let's begin with the supported and certified ones. Today is XOG's turn.

 

What does XOG stand for?

XML Open Gateway (XOG) 

 

 

Where do we download it from?

  • Login on CA PPM.
  • Go to Administration menu.
  • Under General Settings, Go to "Client Downloads".

 

Even I'm using a windows machine to run XOG client, I always download the "Cross-plarform ZIP".

 

** Note: It's important you use the right XOG client tool version according to you CA PPM version. Do not use a different XOG client version, specially if your current CA PPM version is higher. 

 

 

How do we configure it?

There isn't any console or user interface. It's just a command line tool, but you can adjust some settings.

When you extract ZIP file, under "bin" folder we can find may files. The one we really need to modify is the xog.bat.

 

 

By default,  memory assigned is -Xmx512

 

set PROGRAM_ARGS=%SSL_DEBUG_ARG% -Dfile.encoding=UTF-8 -Xmx512m -Dniku.home="%NIKU_HOME%" -Dforehead.conf.file="%NIKU_HOME%\bin\xog.forehead" com.werken.forehead.Forehead -installDir "%NIKU_HOME%"

 

If you have available RAM on your local machine, I encourage you to increase the memory. It will help when xogging large data and avoid out of memory issues.

 

A part from that, I would not change anything else.

 

 

How do we use it?

Let's go to show a very simple example by using a template provide within XOG client tool.

When you extract ZIP file, under "xml" folder there are many XML templates:

 

 

For demo purposing, I will use the prj_projects_read.xml. 

With that template, we will be able to extract project data in XML.

Edit the file with an advanced editor. [ I like to use notepad++  ]

 

From:

<?xml version="1.0" encoding="UTF-8"?>
<NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_read.xsd">
  <Header version="6.0.11" action="read" objectType="project" externalSource="NIKU">
    <!-- you change the order by simply swap 1 and 2 number in the name attribute -->
    <args name="order_by_1" value="name"/>
    <args name="order_by_2" value="projectID"/>
    <args name="include_tasks" value="true"/>
    <args name="include_dependencies" value="true"/>
    <args name="include_subprojects" value="true"/>
    <args name="include_resources" value="true"/>
    <args name="include_baselines" value="true"/>
    <args name="include_allocations" value="true"/>
    <args name="include_estimates" value="true"/>
    <args name="include_actuals" value="true"/>
    <args name="include_custom" value="true"/>
    <args name="include_burdening" value="false"/>
  </Header>
  <Query>
<!--
    <FilterByCustomInfo name="project_billability" criteria="EQUALS">proj bill</FilterByCustomInfo>
    <FilterByCustomInfo name="first_bill_date" criteria="BETWEEN">1999-01-07,2002-07-01</FilterByCustomInfo>
    <FilterByCustomInfo name="project_risk" criteria="EQUALS">Medium</FilterByCustomInfo>
    <FilterByCustomInfo name="profitable_project" criteria="EQUALS">true</FilterByCustomInfo>
    <FilterByCustomInfo name="owner" criteria="EQUALS">last</FilterByCustomInfo>
   -->


<!--
      <Filter name="projectID" criteria="EQUALS">test</Filter>
    <Filter name="active" criteria="EQUALS">true</Filter>
    <Filter name="approved" criteria="EQUALS">true</Filter>
    <Filter name="closed" criteria="EQUALS">false</Filter>
    <Filter name="approvedForBilling" criteria="EQUALS">false</Filter>
    <Filter name="start" criteria="BETWEEN">1999-01-07,2001-01-15</Filter>
    <Filter name="finish" criteria="EQUALS">Customer</Filter>
    <Filter name="lastUpdatedDate" criteria="EQUALS">2002-01-26T11:42:03</Filter>
    <Filter name="resourceID" criteria="EQUALS">jsmith</Filter>
    <Filter name="trackMode" criteria="EQUALS">2</Filter>
   -->

  </Query>
</NikuDataBus>

 

To:

<?xml version="1.0" encoding="UTF-8"?>
<NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_read.xsd">
  <Header version="6.0.11" action="read" objectType="project" externalSource="NIKU">
    <!-- you change the order by simply swap 1 and 2 number in the name attribute -->
    <args name="order_by_1" value="name"/>
    <args name="order_by_2" value="projectID"/>
    <args name="include_tasks" value="false"/>
    <args name="include_dependencies" value="false"/>
    <args name="include_subprojects" value="false"/>
    <args name="include_resources" value="false"/>
    <args name="include_baselines" value="false"/>
    <args name="include_allocations" value="false"/>
    <args name="include_estimates" value="false"/>
    <args name="include_actuals" value="false"/>
    <args name="include_custom" value="false"/>
    <args name="include_burdening" value="false"/>
  </Header>
  <Query>
      <Filter name="projectID" criteria="EQUALS">PR_00001</Filter>
  </Query>
</NikuDataBus>

 

Basically, I just removed all code which is not needed:

1- By setting to "false" data I don't want to include in my XML output file

2- By removing all filters except one:  "projectID" for extracting one single project (PR_00001).

 

Save the modified XML file under another location which is not the template ones. In that way, you always keep a copy of the original file.

 

For this example, I will save it under "bin" folder to make it easier.

 

Now, we are ready to XOG  

 

From a command line shell (like CMD on Windows), proceed as below:

C:\xogclient\bin>xog

Warning: JAVA_HOME environment variable is not set.

-----------------------------------------------------------
PPM XML Open Gateway ( version: 15.1.0.149 )
-----------------------------------------------------------
Usage: xog

login [user/passwd@host:port] Create new active session.
logout Close active session.
call <file> Invoke given XOG request.
verbose <on|off> Turn on verbose error logging.
output <console|path> Output to console or file.
exit Logout and exit the shell.
? Display this help information.

Examples:
call xml/cmn_users_read.xml
> login admin/Abcd1234@gaiau01-u185173:15101
Login: admin@gaiau01-u185173:15101
Login Succeeded
> output PR_00001.xml
Directing command output to PR_00001.xml
> call prj_projects_read.xml
Request Document: prj_projects_read.xml
Writing output to PR_00001.xml
XOG Processing completed !

> exit
Logout Succeeded
C:\xogclient\bin>^A

 

So, all commands used are:

  • xog - to execute xog.bat
  • login - to login with user with XOG rights, specify the hostname or IP and the port.
  • output - to provide the file name for XML output. You can also specify location, if you don't, it will create it under "bin" folder, where xog.bat is located.
  • call - specify the XML input file. You can also specify location, if you don't, it will create it under "bin" folder, where xog.bat is located.

 

As mentioned, the XML output file named "PR_00001.xml" is now saved under our "bin" folder:

 

 

** Note: You can also invoke XOG using one single command line to login, output and call. For demo purposing, I kept it in multiple steps.

 

And if it's SSL ... ?

Same steps, the only variance is we need to use:

xog -sslenabled=true

 

 

The rest of commands are exactly the same.

 

 

Advantages

  • It's developed by CA and provided with CA PPM. Possible defects will be supported by CA support.
  • Easy to use. It's a very simple tool.
  • No extra licenses needed.

 

Disadvantages

  • It's designed to just invoke SOAP calls with CA PPM (read/write). No advanced functionalities.
  • It's a command line tool, so there is non UI.

 

 

 

Related links:

 

 

If you need help with XOG, engage CA Services or ask questions in CA Communities.

 

That’s all. Thanks for reading until here. Did you like it? Please, don’t be shy and share it.

Outcomes