Baselines and RESTAPI, what gives?

Customizations
1

I have noticed when trying to use the RESTAPI to retrieve and update baslines, I am not able to access them from the /api/baselines/{site}/ or /api/baseline/{site}/{id} URL, but have to use /api/content/{site}/ or /api/fixlet/{site}/{id}

When I query /api/fixlets/{site}, no baselines show up, but when I query /api/content/{site} then baselines do show up. However the baselines in /api/content have resource identifier URLs that point to /api/baseline and have element tags of Unknown.

<?xml version="1.0" encoding="UTF-8"?>
<BESAPI xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BESAPI.xsd">
    <Analysis Resource="http://test:52311/api/analysis/custom/Scanners/15827" LastModified="Mon, 08 Dec 2014 19:24:35 +0000">
      <Name>Scanner Analysis</Name>
      <ID>15827</ID>
    </Analysis>
    <Unknown Resource="http://test:52311/api/baseline/custom/Scanners/15844" LastModified="Mon, 08 Dec 2014 21:22:50 +0000">
      <Name>Scanner Baseline</Name>
      <ID>15844</ID>
    </Unknown>
</BESAPI>

Finally when creating baselines using the RESTAPI, posting the appropriate XML to either /api/baselines/{site}/ or /api/fixlets/{site}/ does not work, but you have to use /api/import/{site}/

Does anyone know what the heck is going on with Baselines? Am I working around the edge of some well documented strangeness? I am using version 9.1.1088.0 of the server.

1 Like
2

Does anyone know what the heck is going on with Baselines? Am I working around the edge of some well documented strangeness?

The behavior you’re noticing is not documented. Baseline via REST API functionality is incomplete. However, as you know, there are workarounds:

  • To list baselines, use the resource /api/site/{site}/content. Baselines have a Resource attribute containing /api/baseline.
  • To get a baseline, use the resource /api/fixlet/{site}/{baseline id}.
  • To create a baseline, use the resource /api/import/{site}.
  • To delete a baseline, use the resource /api/fixlet/{site}/{baseline id}.
3

We have noticed similar issues with the REST API, and it is definitely undocumented.

Also, why does the REST API report “http” instead of “https” in the resources?

4

That is a bug. It’s been fixed in version 9.2.0.363 of the server. http://support.bigfix.com/bes/changes/fullchangelist-92.txt documents the bug fix with the line “RESTAPI resource links should use https rather than http (issue: 56197)”.

1 Like
5

@Damien … very useful information regarding baselines … could you please elaborate bit about creatng baseline through rest api. in your reply you have mentioned below statement
To create a baseline, use the resource /api/import/{site}.

Could you please give an hint how can i use this to create a baseline.

1 Like
6

The easiest way to do this is to export a baseline from the IEM Console to a .bes file. This will contain the type of XML you need to create a baseline using the /api/import/{site} resource.

Take that .bes file, modify it as necessary, then POST the contents of it to /api/import/{site}

1 Like
7

@grlucche - i have done the same , but i can see it contains lots of fields like action script,relevance,Success Criteria Option etc along with the baseline component name.

Can i create a xml file only on the basis of fixlet names and then import it on TEM?
I dont want to mention all the other components in xml file , because the purpose of this exercise is to automate the baseline creation i.e to avoid selecting required fixlets one by one and then create baseline.

Could you please give me short example of baseline creation using rest api method , it will be very helpful :slight_smile:

8

I think I understand your question correctly. You would like to use the REST API to create a baseline where the baseline BES XML only references constituent fixlets. As far as I am aware, there is currently no way to use the REST API to create a baseline without including significant content from constituent fixlets within the baseline BES XML.

I will provide an example of using the REST API to create a baseline. For HTTP requests, the example will use the IEM CLI tool. The IEM CLI tool is installed in the root server directory. For XML manipulation, this example does not use a specific application, but the notation of the XML XPath query language is used to reference nodes in XML. This example was tested against IEM version 9.2 patch 2 (9.2.2.21, Hans Patch 2).

This example will create a baseline in the master action site, which has site type master, and does not require a site name. The baseline will include two fixlets from the master action site, which has gather URL http://dw001:52311/cgi-bin/bfgather.exe/actionsite for the IEM environment the example was tested against. The two fixlets are contrived for the purpose of this example. The first fixlet, MasterSite_FixletA, has the ID 39. The second fixlet, MasterSite_FixletB, has the ID 40.

Files

baseline_template.bes (5.1 KB)
This BES XML file is a template baseline. It includes a README comment on how to use it to create a baseline from BES XML fixlets.

MasterSite_FixletA.bes (1.1 KB)
MasterSite_FixletB.bes (1.1 KB)
These files are the BES XML for the example fixlets.

baseline.bes (1.8 KB)
This file is the completed baseline BES XML.

Step 1

The fixlets MasterSite_FixletA and MasterSite_FixletB are downloaded:
iem GET /api/fixlet/master/39 > MasterSite_FixletA.bes
iem GET /api/fixlet/master/40 > MasterSite_FixletB.bes

Step 2

baseline.bes is assembled by following the README comment in baseline_template.bes. The baseline was chosen to have the title Create_Baseline_Example, and a modification time of Fri, 13 Feb 2015 17:10:00 -0800. All the other template substitutions were sourced from either the working knowledge of this example, the BES XML file MasterSite_FixletA.bes, or MasterSite_FixletB.bes.

Step 3

baseline.bes is uploaded to the master action site of the root server:
iem POST baseline.bes /api/import/master

The baseline creation is complete.

3 Likes
9

thank you very much Damien for the excellent example. let me go through it and try to implement and test it in our enviorment,

i will get back to you on this post if i face any issues . thanks again :smile:

10

The reason that you must include the full component XML when creating a baseline is because that is what happens in the console when you create a baseline. Baselines contain copies of all of the sources of the components that they contain so that if the source is modified it does not modify the baseline behavior. Baseline components contain pointers back to their sources so that when the sources are updated the baseline can let you know that it has an old copy and it should be resynced to have the updated copy if desired, BUT it is not actually necessary that source of the component be available and the baseline will still function.

This should mean that in some cases I could export a baseline from my infrastructure, send it to you, and you could import it and use it even if you never had access to any of the sources and they never existed on your end… the baseline should still function.

1 Like
11

@Damien , jgstew : Thank you very much for your feedback and suggestion i will definitely try this in my environment… thanks again :smile:

12

Also something to note is that you can also edit the posted baseline by using the following:

  • ‘PUT’ and using ‘/api/fixlet/{site name}/{baseline id}’

You will also need to include the original XML doc or bes file that you used with the edits in order to see the changes on the BES Console.

13

I do not find this is the case. I get a 500 error, “XML Parsing error: \n invalid document structure\n Line 1, Character 1”

This is using precisely the same payload that works with /api/import. Has anyone actually done a successful PUT of a baseline to /api/fixlet? Can you share a code example?

14

Heh! All I have to do is work up the nerve to contradict something publicly and that will cause me to find my mistake. You can PUT a baseline to /api/fixlet. I had a character encoding problem in my code.

So at this point, my view of it is that there is one bug: The fact that /api/site/…/content has <Baseline Resource="…"> and those resource URLs are invalid. That really is a bug.

And then I think less a bug than a “design surprise” issue (APIs should not “surprise” you) is the fact that there is no /api/baseline(s) URL that works like all the others. There should be. And/or you should be able to GET, POST, PUT and DELETE all the basic objects through /api/fixlets. Last time I tried (although it could be due to the same bug on my part that made me say you can’t PUT) I could only POST an actual Fixlet to /api/fixlet…

1 Like