Clarity PPM | Quick Tips: How to Execute a XOG

In this demo video, Dave Matzdorf, Clarity PPM Chief Architect at Rego Consulting, shows us how to execute a XOG read from your Clarity PPM environment.

Last week, Dave gave us a basic overview of XML Open Gateway (XOG), including how to download it from Clarity PPM and find execution files.

“XOG is the only supported method within Clarity PPM of getting information into or out of your Clarity PPM instance,” says Dave.

Execute a XOG | Training Video

Watch Dave demo how to execute a XOG in this training and read his instructions beneath the video player.

https://youtu.be/aba4RggDMbs

Open a XOG Template | Resource Read

So I have my XOG client installed on my Clarity PPM 13 environment, and today I want to XOG out a resource record.

From within my XOG directory, I go into my “xml” directory, and I’m going to grab the XOG template that corresponds to a resource read: “rsm_resources_read.” This means I will be reading a resource from Clarity PPM.

I prefer to always copy the XOG templates out of the XML directory and place them in my “bin” directory to execute the XOG.

You can open up your XOG template in Notepad, Notepad++, WordPad, or any XML editor.

Tell XOG What to Include | True or False Values

Within your XOG read template, you have a series of arguments that will tell XOG what information from the resource record to include or exclude from output.

In this case, we have the ability to include or exclude contact information, management information, any custom attributes you’ve added to your resource object, or any financial data associated with the resource.

<args name=”include_contact” value=true”/>

<args name=”include_management” value=”true”/>

<args name=”include_custom” value=”true”/>

<args name=”include_financial” value=”true”/>

By default, all of this information will be included because the value of the argument is “true.” If you want to exclude any of this information, you can change the value of any of the arguments to “false,” and that piece of information will not be exported through the XOG.

XOG Can Filter for Certain Resources

You also have the ability within the <Query> tag of the XML template to filter for certain resources. XOG includes certain attributes it can filter on in the templates, such as the Role ID of the resource, active or inactive resources, a resource type, or the ID of the resource.

You’ll also see different criteria you can use. In this case, there’s criteria for “EQUALS” and “OR” contained within this XOG template. If you’re using “EQUALS,” you’ll notice you can enter one specific value.

<Filter name=”primaryRoleID” criteria=”EQUALS”>ARCHITECT</Filter>

Whereas “OR” allows a comma-separated list of values.

<Filter name=”resourceType” criteria=”OR”>EXPENSE, MATERIAL</Filter>

Today we’ll be using the Resource ID to filter for just one resource, so I’m going to select my resource ID.

<Filter name=”resourceID” criteria=”OR”>admin%, %admin</Filter>

And I’m going to change the “OR” to an “EQUALS.”

<Filter name=”resourceID” criteria=”EQUALS”>admin%, %admin</Filter>

And I’m going to filter for the admin resource of Clarity PPM.

<Filter name=”resourceID” criteria=”EQUALS”>admin</Filter>

This resource ID corresponds to the ID or the unique name, as it’s sometimes called, on the resource record.

You’ll also notice that there’s an XML comment <!-- that is commenting out the first few lines of my XOG filter, so only the fourth line is going to apply in my filter. I’m going to save this file and close it.

Launch Your XOG Client

Now it’s time to login to my XOG client. In my command prompt, I navigate to my xog bin directory.

C:\xog\bin>

And I execute the command of XOG.

C:\xog\bin>xog

This will launch my XOG client.

See the User in Clarity PPM

I have a specific user set up for this XOG that we can see if we go into the Clarity PPM “Administration” menu > “resources” > and filter for the name of “XOG.”

This is the user that we’re going to be executing the XOG as. You’ll also notice this user has all the security permissions to be able to execute a XOG: “Resource’s Access Rights” tab > “Global.”

Command Prompt | Login and Specify Output File

So getting back to our command prompt, we can execute our login command, which is “Login,” followed by the username of the resource you’re executing the XOG as, forward slash, and the password of the user, followed by the @ symbol and the URL of the environment you’re executing the XOG against.

> Login xogAdmin/Password@regou04.dev.regoconsulting.net:0002

Once you’ve finished entering the full URL and port, press enter, and if you’re successful, it will say “Login Succeeded.”

At this point, I want to specify an output file, since every XOG, whether it’s a “read” or “write,” produces an output file. For simplicity, I’m going to name it “zz,” so it shows up at the bottom of my MS Windows Explorer page, and I’m going to give it an xml file type.

> zz.xml

So I’m now going to execute the call command from my XOG client to call the file.

> call rsn_resources_read.xml

This is the file we edited earlier to filter for the admin user.

If I execute this, I will get a status of “XOG Processing completed!” And you can see that we have a new xml file in our bin directory that will contain the output from the XOG file.

Open the XOG Output File

This output can be opened in Notepad, Notepad++, WordPad, or any XML editor that you use.

You can see the contents of the XOG containing the resource ID, the resource type, the user name, and since we kept all our arguments to “true,” you can see tags for personal information containing the resources name and email address. There will also be another tag for custom information, financial information, and so on, for all the arguments that we left to “true.”

That is how you execute a XOG read from a Clarity PPM environment.