Steps to use Swagger to generate a Conflict Resolution Report

What is Swagger?

Swagger is an interactive interface that can be used for exploring Fenergo APIs.

Swagger provides a built-in Try It Out feature. After selecting the appropriate API endpoint, authenticating and providing the Tenant ID and required parameters, the API can be executed directly from Swagger. Swagger then displays the response returned from the Fenergo tenant.

Required permissions:

At least one of the following permissions is required in Fen-X:

EntityDataAccessAndSearch
EntityGroupManagementAccessAndSearch

How to Generate the Report Using Swagger

Steps -

Navigate to the Fenergo API documentation for EntityData Query V2:
1. Fenergo API Catalogue.
  - https://docs.fenergox.com/api-docs/fenergo-saas-api-specifications/entity-data-apis/entitydata-query-v2
2. Select the Swagger interface for the API.
  - https://api.fenergox.com/entitydataquery/swagger/index.html
3. Switch to v2 definition of the API
  
  Note: The domain should be identified before using Swagger endpoint, because Fenergo API URLs use the tenant's regional identifier.
  
  The Fenergo $DOMAIN$ can be found by navigating to your Fenergo login page.
  
  For the default EMEA tenant, no domain name is required as your login URL will be as below:
  https://app.fenergox.com/Account/Login.
  
  For other tenants, such as emea1b, the login URL will follow this format:
  https://app.$DOMAIN$.fenergox.com/Account/Login
  
  Examples:
  If my App URL is - https://app.emea1b.fenergox.com/Account/Login
  Therefore, my domain is emea1b.
  
  If my App URL is - https://app.nar1.fenergox.com/Account/Login
  Therefore, my domain is nar1.
  
  Append your domain to a Swagger URL as below -
  Taking emea1b as an example -
  https://api.emea1b.fenergox.com/entitydataquery/swagger/index.html?urls.primaryName=EntityData+Query+Web+API+2.0
4. Once the Swagger URL is updated with the correct domain for your tenant.
  Locate and expand the endpoint: /api/v2/entity/report-pre-sign-url

2. Obtain an Access Token and TenantID

Log in to the Fenergo UI and open: Developer Tools → Network Tab
While having the Network tab open, refresh the browser, so the API calls are recorded
Filter requests using 'API' keyword in the search (as highlighted below).
Locate any API request and copy the complete Authorization header value, including Bearer.³
Also locate and copy the value for 'X-Tenant-Id' request header. This is required when executing the API through Swagger.

3. Authorize Swagger

Authorize the token to be used in Swagger:

Paste the complete Bearer token as below, following Step#1 and 2 from the screenshot.
Click 'Authorize'
Confirm Swagger displays Authorized.

Once authorized, select 'Close' to close the dialogue box.

4. Execute the API request

Fenergo API calls require the tenant identifier and authorization information, together with any parameters/body required by the specific endpoint.

Expand the required API operation and select Try It Out.

Provide:

Tenant ID (Copied from the previous step)
Required JSON request body (exact payload for executing the API endpoint)
{
"data": {
"reportType": "ConflictOverwritesReport"
}
}

5. Execute the endpoint

Select Execute.

Swagger sends the request to Fenergo and displays the response returned from the tenant.

A successful response from this endpoint contains a data object with a url property. For example, structurally:

{"data": 
{     
"url": "<pre-signed URL>"   
},   
"messages": [] 
}

Copy the pre-signed URL returned in the API response.

Paste the URL into a new browser tab to access/download the generated report.

Frequently Asked Questions

Q: How long is the Swagger Bearer token valid?
The Fenergo access token used to authorize Swagger has a default Time to Live (TTL) of 900 seconds (15 minutes). Once that period expires, the token will no longer be accepted for API calls.¹

The short lifetime is a security measure that reduces the period during which a token could be used if it were compromised.²

Q: What should I do if my Bearer token expires while using Swagger?
Retrieve a new access token and authorize Swagger again:

Fenergo UI → Developer Tools → Network → filter api → select an API request → Authorization header → copy the complete Bearer ... value → Swagger → Authorize → paste the new value.³

Tip: If Swagger was working and then API requests stop authenticating after approximately 15 minutes, token expiry should be one of the items you check.

Retrieve a fresh Bearer token and re-authorize Swagger before retrying the request.