Troubleshooting

Log-files

Logs can be found from ESM UI from Administration  Maintenance  Logs. From here, it is possible to download logs, view logs in browser and check how many open sessions are for viewing different logs. There are three logs that are good for debugging web API errors, these are:

• For dataCardImport com.bitmount.equipment.importing.ValidatingEntityXMLImporter
• For search com.efecte.webservice.SearchController
• For EQL queriescom.efecte.persistence.search.eql.EqlEngine

From logs you can view permission errors and more precise errors for EQL exceptions.

Web API Does Not Return Any Data Cards

Web API does not return any data cards, even though there are data cards have been created to template I’m querying.
This can be a permission issue. If web api user does not have template permissions for given template, search.ws cannot return data cards.

Searching With Non-existing attributeCode

If search.ws is used with non-existing attributeCode, e.g. $nam$ instead of $name$. In this case, web API can give following response:

<?xml version="1.0" encoding="utf-8"?>
<error>
<code>efe-3001</code>
   <description>Invalid search query</description>
   <details>Macros should be preprocessed, not converted to HQL: $nam$</details>
</error>

Meaning that attributeCode $nam$ does not exist in the template.

Searching Data Cards With Typo in WHERE-clause

Search.ws won’t return any data cards or errors if there is a typo in WHERE clause’s attributeCode. For example, you query should be “WHERE $efecte_id$ = ‘INC-000259’ ” but there is a misspelled attribute in query “select entity from entity where template.code='incident' AND $efectei$='INC-000259' ”

This will give an empty response without any errors, because nothing matches to WHERE condition.

DataCardImport Errors

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>04.09.2018 09:43:38</start-time>
   <total-time>0,294</total-time>
   <entities-handled-per-second>3,401</entities-handled-per-second>
   <average-entity-handling-time>0,294</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>0</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>0</entities-created>
   <template-errors>
       <template-error code="workstation">Ignoring entity</template-error>
   </template-errors>
</entity-import-report>

This also can be caused by lack of permissions to template. Check from Administration -> permissions that web api’s role is allowed to create data cards to template. 

Testing Examples

Testing web API requests can easily be done with browser or curl. In browser it is easy to test search.ws requests, especially when browser is able to handle xml. 

Testing with browser

To test search.ws in browser, add /search.ws after ESM instance’s base URL. Below is image of browser testing example with following URL:

https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,subject,description,status&query=select%20entity%20from%20entity%20where%20template.code=%27incident%27

Testing With Curl

One option for testing web API is curl. Below is example curl command which does the same query as the browser example.

curl -X GET -u "webapi:Apitest" -L https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,subject,destus&query=select%20entity%20from%20entity%20where%20template.code=%27incident%27

Example response below:

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
<entity id="19406" name="Test incident2">
   <template id="2597" name="Incident" code="incident"/>
   <group code="incident_management"/>
   <attribute id="2612" name="Incident ID" code="efecte_id">
       <value>INC-000278</value>
   </attribute>
   <attribute id="2623" name="Status" code="status">
       <value>1 - Untouched</value>
   </attribute>
   <attribute id="2632" name="Subject" code="subject">
       <value>Test incident2</value>
   </attribute>
</entity>
</entityset>

Importing data cards work in similar way, in this example incident xml is in importdata.xml file:

curl -X POST -H "Content-Type: application/xml" -d @importdata.xml  -u "webapi:Apitest" -L https://localhost:8080/esm/dataCardImport.ws?folderCode=incident_management

Response should be something like example below:

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>14.09.2018 10:44:48</start-time>
   <total-time>0,378</total-time>
   <entities-handled-per-second>2,646</entities-handled-per-second>
   <average-entity-handling-time>0,378</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>