How to interact with Aegis Webservices from external systems

How to interact with Aegis Webservices from external systems

When the topic of web services comes up with Aegis, it is normally in relation to Aegis connecting to a remote system as part of an automation. The other occasion however is when you need some remote system to talk to Aegis. It may be that you want an external tool for example to create an event in Aegis to trigger an automation or to get some information about an existing workitem. This post will look at how this can be achieved.

First of all I will point out that there are a lot more web services available externally than the documentation provides (and therefore what technical support can help with). If there is something you need to do it would be worth contacting Professional Services who may be able to help.

So the first thing to do is to find the help for the Web Services which are available here:

https://<aegis_bsl_server>:8092/Aegis/Integration/RESTful/help
https://<aegis_bsl_server>:8092/Aegis/IQConnect/RESTful/help

Where the <aegis_bsl_server> is the server where the Aegis Business Service Layer is installed (Web Server Computer). Integration and IQConnect are the documented web services.

As well as the RESTful web services, you can also interact with the web services via SOAP. For information on the WSDL available goto:

https://aegis_bsl_server:8092/Aegis/Integration

and

https://aegis_bsl_server:8092/Aegis/IQConnect

So now we can get started. This post will perform the task of generating an event in Aegis via the Aegis web service. The first step is to login to Aegis which provides us with a sessionid token for all other operations.

To login we use the Login method which is available on both the IQConnect and Integration web services. Also note here if you are not using a secure connection for the webservice then the username and password will be transmitted in clear text for the Login method and sessionID for other methods which is a security risk. The sessionID once obtained is valid on all web services.

The help provides this information about the login method :

Url: https://sigea-aeg00:8092/Aegis/Integration/RESTful/Login?userName={USERNAME}&password={PASSWORD}&hostName={HOSTNAME}&portNumber={PORTNUMBER}

HTTP Method: GET

This is a simple HTTP Get method, so we can simply put the URL into a browser and as a test to perform the login. hostName and portNumber are usually not required unless the webservice for some reason is unaware of the location of the IQRM Server location. The hostName will be the hostname of the server running IQRM, and the port will be 10117 by default. It is also possible to create an event in a different Aegis system by specifying the host and port.

If I add this link to my server into a browser I get the following response:

https://sigea-aeg00:8092/Aegis/Integration/RESTful/Login?userName=sigea\cotterm&password=fakePassword

d1

Getting a valid sessionID indicates a successful operation. A failure such as authentication error will generate a message like:

<NamespaceLogonFault xmlns="http://www.attachmate.com/Aegis/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CannotAuthenticate>true</CannotAuthenticate>
<CannotConnect>false</CannotConnect>
<CannotImpersonate>false</CannotImpersonate>
<HostName>sigea-aeg00</HostName>
<IQConnectNativeResultCode>VOS_NOT_AUTHENTICATED</IQConnectNativeResultCode>
<IQConnectResultCode>VOS_NOT_AUTHENTICATED</IQConnectResultCode>
<PortNumber>10117</PortNumber>
<UserName>sigea\cotterm</UserName>
</NamespaceLogonFault>


This also provides good information like the HostName and PortNumber used to connect to IQRM - if these values are incorrect they will need to be supplied as parameters in the URL as mentioned above.
The sessionID can now be used for other operations. The sessionID is valid for 24 hours from its last usage (so it can be constantly renewed).

Next lets create an event in Aegis. We will use the HTTP Post method PostEvent to generate the event. If you have previously used the command line tool method (using generateAegisGenericEvent.exe) to generate Aegis Events you will be familiar with the fields required to generate events. The event definition is sent in the body of the HTTP request in either JSON or XML format. You will also notice that the REST URL for the method is given as:

Url: https://sigea-aeg00:8092/Aegis/Integration/RESTful/PostEvent?sessionID={SESSIONID}&userName={USERNAME}&password={PASSWORD}&hostName={HOSTNAME}&portNumber={PORTNUMBER}

As we already have used the login method, you only need specify the sessionID parameter. However you don't need to use login at all if you don't to, instead you can specify username and password each time but getting the sessionID is better practice.

The examples provide all the possible fields which can be used. You do not need to use all fields, but they must be in the same order as provided or the method will most likely work as expected. So for example we can create an event using this XML as the body:

<PostEventInfo xmlns="http://www.attachmate.com/Aegis/">
<CustomData1>System XYZ</CustomData1>
<CustomData2>cotterm</CustomData2>
<Message>System Status Message</Message>
<Name>SystemStatusEvent</Name>
<Severity>NotNoteworthy</Severity>
<Status>New</Status>
</PostEventInfo>


Note that depending if you send the data in XML or JSON you will need to ensure you escape special characters in the values correctly.

The response data includes the Aegis eventID which was generated \:

<PostEventResult xmlns="http://www.attachmate.com/Aegis/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<EventID>e0d55719-afad-4083-8f34-00c37af7c8a1</EventID>
</PostEventResult>


The event in Aegis is raised as an Aegis Generic Integration Event.

d2

Once an event is created, depending on the capability of the external system you may want to do more than jut create an event. You may want to wait and see if this event is associated with any workitems and the progress of any of these workitems! At this point you'll probably see that there is no specific methods available to do what I just mentioned! So how can it be done? Via the RunVQLQuery in the IQConnect webservice. Describing VQL is outside the scope of this post - but the following VQL can be run to find workitems triggered by the event we just created. Run this first in the Namespace Browser to verify substituting in your eventid. In a workflow this would be done dynamically using input builder.

SELECT PG_Event2WorkItemAssociation.iqcimRhsAssociate FROM PG_Event2WorkItemAssociation (PG:'/PG_TopLevelContainer=PG') WHERE PG_Event2WorkItemAssociation.pgMappingFlags -eq 1 && PG_Event2WorkItemAssociation.iqcimLhsAssociate -eq 'e0d55719-afad-4083-8f34-00c37af7c8a1';

RunVQLQuery method requires a POST to this URL:

https://sigea-aeg00:8092/Aegis/IQConnect/RESTful/RunVQLQuery?sessionID={SESSIONID}

with Post Data:
<RunVQLQueryInfo xmlns="http://www.attachmate.com/Aegis/">
<QueryString>{VQL Query}</QueryString>
<RetrieveSchema>false</RetrieveSchema>
</RunVQLQueryInfo>


where {VQL Query} is the VQL query above. Note again that depending if you send the data in XML or JSON you will need to ensure you escape special characters in the query.

This is the expected XML response when a workitem has been triggered by an event. Note the query is only for workitems triggered by the event, not appended etc. Also there could be more than one workitem returned or none.

<IQConnectQueryResult xmlns="http://www.attachmate.com/Aegis/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ResultList>
<IQConnectAttrList>
<List>
<IQConnectAttribute>
<Name>PG_Event2WorkItemAssociation.iqcimRhsAssociate</Name>
<Value>
<Type>STRING</Type>
<Value i:type="IQConnectString">
<StringValue>/PG_TopLevelContainer=PG/PG_WorkItem=299262880</StringValue>
</Value>
</Value>
</IQConnectAttribute>
</List>
</IQConnectAttrList>
</ResultList>
<Schema>
<List />
</Schema>
</IQConnectQueryResult>


It is the StringValue that we want to get which is the locator of the workitem which contains the workitem id.

Next to get details of the workitem, its a simple GET again on this URL:

https://sigea-aeg00:8092/Aegis/Integration/RESTful/GetWorkItemInfo/workItemID={WORKITEMID}?sessionID={SESSIONID}

Via my browser as a simple example:

d3

Enjoy!

DISCLAIMER:

Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Top Contributors
Version history
Revision #:
1 of 1
Last update:
‎2016-03-31 20:48
Updated by:
 
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.