HxGN EAM ION API Swagger

Hexagon Documentation

Generated 02/10/2025
Table of Contents
HxGN EAM™ ION API Swagger
Related documents
Version information
EAM configuration for setting up ION API
Setting up ION API for EAM
Swagger documentation for EAM
Using ION API in ION document flow
Using ION API in ION workflow
Security
Accessing ION API service from a client
Accessing ION API Service from Mobile client
Creating a service account
Custom bods
Creating policy definitions
Customer Support and Technical User Forum
Hexagon Policy Against Software Piracy
HxGN EAM™ ION API Swagger
This document provides information about using the ION API gateway with EAM as a target endpoint.
Using ION API enables you to access EAM application's services from ION Workflow, ION Document
Flow, and more giving your application much more exposure across the Infor® portfolio of applications

The high-level architecture of the ION API gateway for EAM is illustrated in this diagram.

Customer Support and Technical User Forum

Hexagon Policy Against Software Piracy
Copyright © 2022, Intergraph Corporation <https://hexagon.com/products/product-groups/aec-software/aec-office-software> and/or its subsidiaries and
affiliates
11.07.01
Published Tuesday, October 11, 2022 at 7:10 PM

Related documents
See these documents for more detailed instructions:

HxGN EAM Installation Guide

HxGN EAM™ Product Family Software Requirements

HxGN EAM System Administrator Guide

Infor ION® Development Guide

Infor ION® Desk User Guide

Swagger documentation for the EAM EWSConnector is attached to this PDF. The attached files include:

AnyDocument.xml

EAMApi.json

JsonTransformation.xml
 SyncEnvelope.xml

To access these files, select View > Show/Hide > Navigation Panes > Attachments. For more
information on these files, see Swagger documentation for EAM.

Version information
Versions of the application that are used for this POC:

HxGN EAM version 11.4.x or later

Infor® OS version Infor Ming.le® 12.0.23.30 or later and Registry 696

Infor ION® version 12.0.23 or later

EAM configuration for setting up ION API

1. If the user is using On-Premise version of Infor® OS then EAM should be deployed with tenant as
infor otherwise the user has to use ION API’s endpoint’s tenant header policy to explicitly define
other tenant.

2. Set the install parameter ‘LGNCON’ to EXTERN in EAM.

3. Enable single sign on (SSO) for EAM.

4. See HxGN EAM Single Sign-On Guide to enable SSO

5. The user should log in to EAM using the email ID and NT password.

6. Once successfully logged in, you will find your user in the User Setup.

7. Select the Connector check box for the current logged in user.

8. Configure EAM for OAuth 1.0 Authentication.

Setting up ION API for EAM

For On-Premise EAM :

1. Go to Infor ION® API after logging into Infor® OS.

2. Create a new API suite by clicking on Add New API suite.

3. To create a Non-Infor suite for EAM click Create New.

4. Provide the suite information as shown in this screenshot:

5. Define the EAM target endpoint

Target Endpoint URL: http://<eamserver>:<port>/axis/services, the url can be a http or a

https url like https://inhywxxxxxxx.infor.com:447/axis/services

Proxy Endpoint URL: EWS (can be any name)

Public Facing URL will be built with the above information.

Proxy Endpoint Security: Anonymous/Oauth 2

Target Endpoint Security: Anonymous/Oauth 1a

 6. You can use the public facing ION API URL to access the target endpoint from the client.

https://<mingleserver>:port/<tenantId>/CustomerApi/<contextname>/<proxy_end_pointurl>

https://inhyxxxxxxxxx.acme.com:7443/infor/CustomerApi/eam_api/EWS

In the above URL:

Tenant is infor for on-premise deployments. For cloud deployments refer "For Cloud EAM"
section

CustomerApi is a constant which is generated by the application.

eam_api is the context defined in the API interface screen shown in point 4.

EWS is the proxy endpoint URL name shown in the above screen shot.

If you want to enable Oauth security for Target Endpoint and Proxy endpoint, see
Option 2 in the "Security" section of this document.

For more information on ION API see the Infor ION® API Administration Guide.

For Cloud EAM:

The user needs to select Infor® Provisioned Infor EAM® suite

In the Endpoints screen we have two endpoints,

EAM API Services

This endpoint will have EAM webservice as target endpoint, This will not be seen in ION API Connector
in ION Desk and also you cannot use the ION API "Try It Out" to make test requests to the target
endpoint as there is no documentation defined for it.

EAM API with Swagger Documentation

This endpoint will also have EAM webservice as target endpoint with swagger documentation (Refer
Swagger Documentation for EAM section for more information) defined for it, The user can use this
endpoint in ION Desk->ION API Connector and ION API flows

The "Try It Out" feature of ION API can also be used to make request in the ION API screen itself

Since the documentation pre-built the user cannot define the Suite and Endpoint policies like we define
in Non-Infor suite

The proxy endpoint url will have EWSConnector at the end

https://<server>:<port>/<TenantId>/EAM/axis/services/EWSConnector
The below screen shows how the EAM proxy endpoint can seen in ION API Connection point

Swagger documentation for EAM

What is Swagger?
Swagger is an API documentation tool which exposes the API documentation on a webapp. It shows
the endpoints and their parameters and allows you to run requests as a client. It is a very useful tool
when you need to simulate a third-party application making requests.

Since EAM endpoint is a soap web service it will not have the swagger documentation by default for
on-premise version. Therefore, you should build custom swagger documentation for our
EWSConnector externally and upload it to the ION API defined above so that the ION API will recognize
the service and will be available as part of ION API Metadata.

The Swagger documentation for the EAM EWSConnector that we built is attached to this PDF in the
Attachments pane. Open the file and change the host, which is the EAM service host name, and the
basePath defined in the above ION API.

For Cloud versions we have the documentation already defined as part of "Infor Provisioned" Infor
EAM® suite and the below steps are not required,

1. Upload the documentation to ION API.

2. After successfully uploading you will find the swagger documentation as shown here.
3. When you click on the EWSConnector link you can try the sample testing using this
documentation and check if you are getting the expected response for your EAM webservice
request

4. Request

After sending the request to the endpoint, you will get a status code of "200" if the server
response is successful. You can find the response in the Response body as shown here.

After sending the request to the endpoint, you will get a status code of "500" if the request
fails. You can see the details of the failed response in the Response body as shown here.
Using ION API in ION document flow
Defining the ION API connection point
In order to use ION API in a document flow you must first define an ION API connection point.

1. Provide all the required connection point information like Name and Description.

2. On the Connection tab, import the service account. Go to the Creating service account section to
learn more about service account.

3. The supported scenarios for the ION API Connection point

Get from API - Request a response from API. Use the data from the response to send an output
document.

Send to API - Use the data from the input document to send a request to API.
 Trigger API - Combination of Get and Send API, Use the data from the input document to send a
request to API. Use the data from the response to send an output document.

4. Now we will use Trigger API scenario. On the Documents tab, click Add Document and select the
Trigger API.

5. The use case used for this scenario includes taking a SyncEnvelope custom bod or AnyDocument
as an input document and making a request to ION API for getting the default parts.

The SyncEnvelope BOD and Any Document is attached to this PDF in the Attachments pane.

6. For this use case, you need to select SyncEnvelope or AnyDocument on the Document To Receive
tab.

7. On the ION API tab, select the API you defined in the Infor ION® API screen.

8. On the Request Body tab, select the format as "text/xml" and Name should be inputXml.
 9. On the Output Document tab, to get an xml to output from the API, use the Document type as
AnyDocument and format as text/xml.

10. You can make a make a test call to the Target endpoint to check if the details provided are good,
you can use the Test Connection option, while making the test request make sure the HTTP
headers in the Input Request Parameters should always be "text/xml" for Accept and Content-
Type headers as shown below as EAM webservice will only cater soap request XML’s.
 11. If you want to map file fields from the Input document to the Input API request you need to select
the Map input document to API Request check box and give the request xml with place holders.

You can use <IonApiRef> tag as a place holder as shown here.

For more information on <IonApiRef> see the Infor ION® Technology Connectors Administrative
Guide.

Defining the document flow

To define the document flow, select the ION API model and give it all the properties that defined in the
connection point, like API connector information and Document.

Use case considered for creating a document flow in ION

Part is created in HxGN EAM.

EAM publishes SyncItemMaster bod.

Convert the SyncItemMaster to SyncEnvelope using a mapper or an XSLT.

SyncEnvelope bod which has a GetParts soap request will be used as input document and
Consume the SyncEnvelope from the shared folder via a File Connector without using a mapper
You can you <IonApiRef> tag if you want to give dynamic input from the ItemMaster to the
SyncEnvelope custom bod.

For more information on <IonApiRef> see the Infor ION® Technology Connectors Administrative
Guide.

The ION API will make a service call to EAM and receive the response as AnyDocument
(Response XML).

The file connector will write the response to a share folder.

Once all the configurations are done, activate the flow and create a part in EAM or create a
SyncEnvelope Bod and place in a share folder for the file connector to pick.
 On successful execution of the document flow you should be able to see a Response xml as Any
Document with GetPartResults information.

The possible ways in which you can make a request to ION API using the ION API Document handle the
response

Use the Input document as AnyDocument and process the Output Response of the ION API call to
AnyDocument where you will place the soap EAM request with <MP0241_Getpart_001> as part of
the AnyDocument as shown here.

Use the Input document as Custom bod like SyncEnvelope and process the Output Response of
the ION Api call to AnyDocument.

For more information on custom bods please see the Infor ION® Desk User Guide.

Use the Input document as a standard bod like SyncItemMaster and Map the bod to a
SyncEnvelope Custom bod or a AnyDocument type and process the Output Response of the ION
 Api call to AnyDocument or some supported format.

Input AnyDocument is attached in the Attachments pane.

Using ION API in ION workflow

Use case considered for workflow
Create a requisition in EAM.

SyncRequisition will be published by EAM.

Create a task in workflow which consumes the SyncRequisition and checks the status. If the
Status is approved, then make a request in the ION API in workflow which will get/update the
requisition description from/in EAM.

Once the ION API request via workflow is successful, then take the output body (Response result
xml) and process the description to a Notification.

Defining the workflow

1. Define the workflow with type as ION API.

2. On selecting the ION API in the workflow modelling area you will see the ION API Properties.

3. On the ION API tab, select the API (eam_api) that is defined on the Infor ION API screen.

4. Import the service account. Go to the Creating service account section to learn more about
service account.

5. On the Input Body tab, provide the soap request xml.

 6. On the Output Parameters tab, you can map the response result xml to a workflow parameter,
from the response you can select the body and map the description to a REQUISITIONDESC
workflow parameter. For this you can use the description xpath of the response xml body as
follows:

Envelope//Body//MP1213_GetReq_001_Result//ResultData//Req//REQUISITIONID//DESCRIPTION

7. Test the call to API by using the Test API Call.

8. Define an Activation Policy and use the workflow defined above to be part of the policy.

9. Activate both Workflow and Activation Policy. Workflow should be able to make an API request
whenever EAM publishes a Requisition.

Security
The grant type used for communication between ION and ION API is Password Credentials but for
some reason the X-Infor-Identity2 and Tenant information is null in the EAM Oauth Authorization map.
Therefore, there are two options to proceed. And this is applicable for On-Premise version only as we
are going with Non-Infor suite of ION API.

For cloud EAM this will be handled by ION API only.

Option 1
Specify OAuth2.0 for Proxy Endpoint Security and OAuth1.0a for Target Endpoint Security.

Now that the X-Infor-Identity2 and Tenant information is missing the Oauth Authorization map in EAM,
you can provide it in the Endpoint policies as header information.

The input xml soap request xml will be different if you use oauth security. Now that the security is
enabled, the request to EAM will be handled by a Bearer token and you will not user information as part
of the soap request xml.

See this sample request that you will provide in the input xml section of ION Connection point and ION
workflow.
If the user want to use Https url as target endpoint,
Enabling the Ignore Certificate Errors flag will solve the certificate issue if any (Step-1)
If the customer does not want to ignore the certificate errors by enabling it, then he needs to import the
target endpoint SSL certificate (Step-2).

Option 2 (Not Recommended)

Specify Anonymous for the Proxy Endpoint Security and Target Endpoint Security.

By doing so the input request will be the plain EAM soap request as shown here. This request you will
provide in the input xml section of ION Connection point and ION workflow.
You can use JsonTransformations as the endpoint policies in the header of the soap request xml. This
is applicable only for on-premise version of EAM where we are using "Non-Infor" suite of ION API

The sample JsonTransformation is attached to this PDF in the Attachments pane.

Accessing ION API service from a client

We can access the ION API service from any client like java client or REST client. We will use Postman
<https://www.getpostman.com/> to make a request to ION API using OAuth. In the Authorized Apps of
ION API the Backend service type is used to get the authorization credentials.
Authorization tab

Data for the fields here are obtained from the .ionapi file you downloaded from Authorized Apps to be
filled in GET NEW ACCESS TOKEN screen as mentioned here:

Token name could be any name

Grant Type is "Password Credentials"

Access Token URL = pu + ot

eg. pu = https://<hostname>:<port>/<TenantID>/as/

ot = token.oauth2

= https://<hostname>:<port>/<TenantID>/as/token.oauth2

Username = saak

Password = sask
 Client ID = ci

Client Secret = cs

Leave Scope as blank

Client Authentication is “Send client credentials in body”

Once you fill all the fields you need to request a token on successful generation the user will be
provided with a Bearer token.
You need to use the token for you request to ION API

Header tab
You need to provide the header as shown here:

X-Infor-TenantID – which is "infor" as we are using a premise version of ION API in case of cloud
you need to mentioned the corresponding cloud tenant

Content-Type should "text/xml"

X-INFOR-IDENTITY2 should be the mingle userusig which you generated the .ionapi for the
Authorization tab.
Body tab
The body should have the actual soap request that you are intended to fire to the target endpoint as
shown here:

Accessing ION API Service from Mobile client

For Mobile clients, you must download the credentials using the Authorized App type as Mobile-
Android/Mobile-iOS, etc. While configuring the Access token policy and validity information in
Authorized apps of ION PI, the mobile application should implement the callback mechanism in the app
and give the callback URL as a Redirect URL: com.infor.eam://oidc_callback

After successful authentication from the authentication server, this Redirect URL call back should help
the application to redirect home page of EAM mobile app or display an error message if the
authentication is unsuccessful
Once all the details are provided the user will receive a client key, secret key, and QR code.

The QR code will have the information of the Authenticating Server and the Tenant. Once the mobile
user scans the QR code, the authentication server and the tenant details will be available with the
mobile client and stores as mobile app settings. This is like the QR Code scan functionality in EAM.
Creating a service account
To use ION API in an ION document flow or a workflow you need to define a service account and import
it.

You can create a service account in Mingle User Management.

Once the service account is created, download the account as a CSV file.

While creating the ION document flow or workflow, import the service account to use the ION API in the
flows.

This service account will be used by ION to get the ION API metadata.
Custom bods
We have used Envelope custom bod in the Document flow and workflow. We have created the custom
bod for GetPartDefaults service of EAM as you can see in this screenshot.

You can create custom bod by following the steps from the Infor ION® Desk User Guide.

Creating policy definitions

<header xmlns="" xmlns:xsi="" name="header-example" displayName="header-example"
enabled="true" version="1.0">

<action>set</action>

<headerName>Content-Type</headerName>

<headerValue>text/xml</headerValue>

</header>
Customer Support and Technical User Forum
For the latest support information for this product, use a web browser to connect to the Smart
Community <https://smartcommunity.hexagonppm.com/> . You can submit any documentation
comments or suggestions you might have by logging on to our documentation web site at
https://docs.hexagonali.com <https://docs.hexagonali.com> .

To access the Technical User Forum, go to https://www.linkedin.com/groups/873447/

<https://www.linkedin.com/groups/873447/> .

Hexagon Policy Against Software Piracy

When you purchase or lease Hexagon’s Asset Lifecycle Intelligence division software, Hexagon,
Intergraph, or its affiliates, parents, subsidiaries retains ownership of the product. You become the
licensee of the product and obtain the right to use the product solely in accordance with the terms of
the Intergraph Corporation, doing business as Hexagon’s Asset Lifecycle Intelligence division, Software
License Agreement and applicable United States and/or international copyright laws.

You must have a valid license for each working copy of the product. You may also make one archival
copy of the software to protect from inadvertent destruction of the original software, but you are not
permitted to use the archival copy for any other purpose. An upgrade replaces the original license. Any
use of working copies of the product for which there is no valid Intergraph Corporation, doing business
as Hexagon’s Asset Lifecycle Intelligence division, Software License Agreement constitutes Software
Piracy for which there are very severe penalties. All Hexagon software products are protected by
copyright laws and international treaty.

If you have questions regarding software piracy or the legal use of Hexagon software products, please
call the Legal Department at 256-730-2362 in the U.S.

Updated June 2022

Document No. DDGL562C0

Copyright
Copyright© Hexagon AB and/or its subsidiaries and affiliates. All rights reserved.