Skip to main content

Integrator Introduction

Akinon Integrator facilitates a seamless integration between the customers' system of records and Omnitron. This document will describe the functional capabilities of the product using partner, developer and brand terminology.

You can find detailed explanations of the terminology in the Concept Definitions document.

Login

Once the partner account has been approved by Akinon, the Partner User will be able to log in to the Akinon Integrator application with their own username and password.

Users

The Akinon Integrator application offers project and role-based authorization.

There are there user types in the application; “Partner User”, “Project User” and “Viewer User”.

Partner Users are admin users which are eligible to create as many user as needed within the relevant partner account and determine for which project(s) these users will be authorized.

Note: Initial Partner Users are created by Akinon.

The role-based authorization matrix in the application is as follows:

RoleFunctionViewCreateEdit
Partner UserProjectYesYesYes
Partner UserIntegration FlowYesYesYes
Partner UserTestYesYesYes
Partner UserNotification SettingsYesYesYes
Partner UserUsersYesYesYes
Partner UserLogYes--
Partner UserMonitoringYes--
Project UserProjectYes*NoNo
Project UserIntegration FlowYes*Yes*Yes*
Project UserTestYes*Yes*Yes*
Project UserNotification SettingsYes*Yes*Yes*
Project UserUsersNoNoNo
Project UserLogYes--
Project UserMonitoringYes--
View UserProjectYes*NoNo
View UserIntegration FlowYes*NoNo
View UserTestYesYesYes
View UserNotification SettingsNoNoNo
View UserLogYesNoNo
View UserUsersNoNoNo
View UserMonitoringYesNoNo

*Specific to authorized projects

Steps for adding a new user or updating existing user information/authorization:

  • Click on the User menu in the main menu and select which project you wish to process from the Project Name filter. All users in the relevant project will be listed on screen.

  • Click on +Add New User in the upper-right corner of the screen to add a new user to the project, or click on the User Identity information in the relevant user row to edit the information of an existing user.
  • The User Information page will appear, facilitating the entering/editing of user information.

  • After entering or updating the mandatory user information on this screen, click on Submit.

These steps will allow you to create/update a user account.

Projects

Within the Akinon Integrator application, you can create and manage multiple projects with a partner user.

Steps for creating a new project:

  • Log in to the application with the partner user.
  • Select the Projects menu option from the main menu. All projects in the relevant partner account will be listed on screen.

  • Click on +Create New Project in the upper-right corner.

  • Type the project name into the Project Name field in the pop-up.

Note: Project names must be unique with a maximum length of 20 characters.

  • Then click on Submit to create the project.

The Partner User can edit the project status (“stopped,” “running”). The Play/Pause button on the right side of the Project Card on the Project List page allows the user to stop or run the project at any time. If the project is stopped, all the relevant integration flows will be stopped automatically.

Clicking on a Project Card on the Project List page opens up the Project Landing page, which provides the necessary functionality to manage end-to-end integration in four different steps.

The function content on the Landing page is as follows:

Integration Flow

This menu facilitates the following functions:

  • Listing the existing integration flows in the project,

  • Copying an existing integration flow,

  • Creating a new integration flow,

  • Viewing/editing/updating integration flow settings,

  • Viewing/editing/updating alarm conditions related to the integration flow.

    Clicking on the Integration Flow card lists the previously created integration flows and the relevant general information. The list content can be filtered with the filtering options in the Filters field.

    Using the Select Action field allows the user to copy an existing flow with all its settings and make the necessary adjustments with the Duplicate Flow feature.

    Note: When the list page is first opened, no filter is selected by default. New or copied flows are set to passive status by default. These flows to be displayed in the list and their status to be activated, the Status can be set as Active.

There are thirteen different flow types in the application:

  • Login
  • Product
  • Price
  • Stock
  • Image
  • ImageS3
  • Order
  • Order Status
  • Order Cancel
  • OMS Stock
  • Retail Store
  • Generic Proxy
  • CRM Service

Login flow is a type of flow that must be created if the authentication infrastructure is used to access the services included in any integration flow. Before creating any integration flows of different types in a project, the required Login flows must be created and its necessary settings must be adjusted.

Since the authentication infrastructure is used to access Omnitron services, the Omnitron Login flow is added to the project by default whenever a new project is created. To use the Omnitron Login flow, the necessary settings must be entered into the relevant flow.

If the client has an authentication infrastructure for accessing system of records' services, the Login flow(s) required to access these services must to be created and their settings must be adjusted.

Steps for adjusting an Omnitron Login flow:

  • Select Integration Flow from the project menu.
  • Turn the flow status on.
  • Open the Flow Settings page by clicking on the flow settings edit button on the Omnitron Login row on the listing page that appears.

  • Enter the client's Omnitron URL, and their account's Username and Password on the screen and click on Submit.

Since the login flow(s) to be used in cases requiring authentication to ERP services are not set by default, new Login Flow(s) must be created in line with the user’s needs. Steps for adjusting a non-Omnitron Login flow:

  • Click on +Create a New Flow in the upper-right corner of the Flow List page.
  • Enter the Flow Name and select Login for the Flow Type.
  • Click on Save.

Unlike the Omnitron Login flow settings, the user must also edit the following information in the relevant fields on the Flow Settings screen.

  • Login Type (Some required inputs will appear according to Login Type selection)
  • URL
    • Token Prefix
    • Token Path

After creating the required login flows by following the steps above, new integration flows can be created in the projects.

Steps for creating a new integration flow:

  • Click on +Create a New Flow in the upper-right corner of the Flow List page.
  • On the Flow Settings page, enter the following information for the new integration flow and click on Save.
    • Flow Name
    • Flow Type
    • Login
    • Integration Type
    • Schedule
    • Alarm Condition

Outbound integration type will use when the data is pushed to Akinon Service by the customer. Flow scheduling function is not valid for this integration type and only Omnitron Login Flow is needed, any other login flows for customer's system of records is not needed to be set.

it's only needed to be logged into Akinon Services to be sended the datas successfully when Outbound integration type use. Login information is shown below.


Login Endpoint : /api/nifi/login

Http method : POST

Content-Type : application/x-www-form-urlencoded

Body

  • Username
  • Password

Sample Response

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1aWQ9b2t0YXkuZHV5bWF6QGFraW5vbi5jb20sb3U9bmlmaSxkYz1lbnRlZ3JhdG9yLGRjPWFraW5vbixkYz1uZXQiLCJpc3MiOiJMZGFwUHJvdmlkZXIiLCJhdWQiOiJMZGFwUHJvdmlkZXIiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1aWQ9b2t0YXkuZHV5bWF6QGFraW5vbi5jb20sb3U9bmlmaSxkYz1lbnRlZ3JhdG9yLGRjPWFraW5vbixkYz1uZXQiLCJraWQiOjUzLCJleHAiOjE2MzM0MDEwMDcsImlhdCI6MTYzMzM1NzgwN30.j_RrmPkxpshcuz0bp41tid8EGwOpEQvWh0wZySjYyeU

Outbound Request Endpoint information can be obtained from Activity-Based settings pages as shown below.


Outbound Request Endpoint : /api/p1/partner/project/flow

Http method : POST

Content-Type : application/json

Token Type : Bearer Token

Exameple Body

[{
"sku": "12345672234",
"stock": 19,
"stock_list": 1,
"unit_type": "qty"
}, {
"sku": "WA1D52324552",
"stock": 17,
"stock_list": 1,
"unit_type": "qty"
}, {
"sku": "WA0004232434",
"stock": 35,
"stock_list": 1,
"unit_type": "qty"
}]

Inbound integration type will use when the data is queried from the customer services by Akinon. It has been shown detailed below how to be used inbound integration type.

Schedule: (Valid for “Inbound” integration only.) Determines the timing of the data reading query to be thrown within the integration. There are three different timing options in the application: “Repeat Every,” “Cron Driven” and “Triggered By.”

Alarm Condition: It is the area where the necessary conditions are defined to give a warning if the performance of the integration flow goes beyond the determined limits. There are two different performance metrics used to determine the warning conditions in the application: “Error Rate” and “Avr. Flow Time.”

The relevant integration flow is created in the project based on the information above. To customize the new integration flow, detailed settings must be adjusted based on Flow Activities.

  • After clicking on Save, the user is automatically directed to the Integration Flows Listing page. Activity-Based Settings page can be opened by clicking settings icon on listing page for the related flow. Transitions between activities are made by clicking on the relevant activity boxes on the Flow Designer page.

Note: Activity settings may vary depending on Integration Flow Type. For example, the last step for the integration flows such as Stock, Price, etc., where the data sent from the ERP to Omnitron, will be Writing to Omnitron, and the last step of the integration flows, such as Order and Cancel Order, will be Writing to ERP. However, the Activity-Based settings to be made with the changing Flow Type will also vary.

For instance, the activity settings of the Product integration flow are detailed below.

1. Product

The client’s Omnitron settings and the Parameter settings to be used when sending the request are entered.

2. Read Data From ERP

The necessary settings are made to facilitate the link between the client’s system of records and Omnitron.

3. Script

If the client requires customized controls or adjustments, they may choose the desired coding language and write Custom Scripts.

This screen mainly contains three parts; Input, Script, and Output.

Programing Script block is be entered to progress the script activity. Besides, entering the input JSON, and viewing the output by clicking Transform is not mandatory for the user. However, Input and Output blocks are suggested to be used in order to easify the controlling of written code in the Jolt Specification block.

Input Example:

[
{
"sku": "3333333",
"price": 6040.0,
"price_discounted": 6040.0,
"price_list": "1",
"currency_type": "try",
"tax_rate": 8.0,
"retail_price": 7550.0
},
{
"sku": "2222222222",
"price": 0.0,
"price_discounted": 0.0,
"price_list": "1",
"currency_type": "eur",
"tax_rate": 8.0,
"retail_price": 0.0
},
{
"sku": "1111111111",
"price": 0.0,
"price_discounted": 0.0,
"price_list": "1",
"currency_type": "gbp",
"tax_rate": 8.0,
"retail_price": 0.0
}]

Script examples:

Example 1

import java.io
import json
import traceback
from org.apache.nifi.processor.io import StreamCallback
from org.apache.commons.io import IOUtils
from java.nio.charset import StandardCharsets



class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Write output content
outputStream.write("Hello World!")


flowFile = session.get()
if flowFile != None:
try:
flowFile = session.write(flowFile, TransformCallback(flowFile))
session.transfer(flowFile, REL_SUCCESS)
except:
var = traceback.format_exc()
session.putAttribute(flowFile, 'log.script.error', var)
session.transfer(flowFile, REL_FAILURE)
session.commit()

Example 2

import java.io
import json
import traceback
from org.apache.nifi.processor.io import StreamCallback
from org.apache.commons.io import IOUtils
from java.nio.charset import StandardCharsets



class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Read input content
text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
#Load input json
obj = json.loads(text)
#Write output content
outputStream.write(bytearray(json.dumps(obj, indent=1).encode("utf-8")))


flowFile = session.get()
if flowFile != None:
try:
flowFile = session.write(flowFile, TransformCallback(flowFile))
session.transfer(flowFile, REL_SUCCESS)
except:
var = traceback.format_exc()
session.putAttribute(flowFile, 'log.script.error', var)
session.transfer(flowFile, REL_FAILURE)
session.commit()


Example 3

import java.io
import json
import traceback
from org.apache.nifi.processor.io import StreamCallback
from org.apache.commons.io import IOUtils
from java.nio.charset import StandardCharsets



class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Read input content
text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
#Load input json
obj = json.loads(text)
#Write output content
outputStream.write(bytearray(json.dumps(obj, indent=1).encode("utf-8")))


flowFile = session.get()
if flowFile != None:
try:
flowFile = session.write(flowFile, TransformCallback(flowFile))
session.transfer(flowFile, REL_SUCCESS)
except:
var = traceback.format_exc()
session.putAttribute(flowFile, 'log.script.error', var)
session.transfer(flowFile, REL_FAILURE)
session.commit()

Example 4

import java.io
import json
import traceback
from org.apache.nifi.processor.io import StreamCallback
from org.apache.commons.io import IOUtils
from java.nio.charset import StandardCharsets



class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Read input content
text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
#Load input json
obj = json.loads(text)
#Transform content
index = 0
for item in obj:
item['newField'] = 'NewFieldIndex{}'.format(index)
item['tax_rate'] = item['tax_rate'] + 2
index+=1
#Write output content
outputStream.write(bytearray(json.dumps(obj, indent=1).encode("utf-8")))


flowFile = session.get()
if flowFile != None:
try:
flowFile = session.write(flowFile, TransformCallback(flowFile))
session.transfer(flowFile, REL_SUCCESS)
except:
var = traceback.format_exc()
session.putAttribute(flowFile, 'log.script.error', var)
session.transfer(flowFile, REL_FAILURE)
session.commit()



4. Mapping

Jolt Transformation language is used in the mapping activity. This activity facilitates the matching of Keys on the client’s system of records with Keys on Omnitron.

This screen mainly contains three parts; Input, Specification, and Result.

Jolt Specification block is be entered to progress the mapping activity. Output of written mapping can be seen in the last step named "Result" with JOLT Code prepared by using JOLT interface.

Note: The Keys on the left side of the Jolt Specification block represent the Keys from the client's system of record, and the Keys on the right represent the Keys on Omnitron.

  • The “Save output as pre-products?” field is used to determine whether the product to be sent at the Mapping stage will be sent to Pending Products or directly to the Product Pool for the relevant product integration flow.
    • If the input is set to “No”, the products are sent directly to the product pool. (Note: The product’s Attribute Set information must also be sent in the mapping code for this option).
    • If the input is set to “Yes”, the product will be sent to the Pending Products list. (Note: Attribute set parameter is not needed for this option, they are set to be arranged through Omnitron)

Note: The “Save output as pre-products?” field is only available for Product Flow.

Mapping Code Block Example:

                                      
{
"operation": "shift",
"spec": {
"\*": {
"extra_attributes": "[&1].extra_attributes",
"product_type": "[&1].product_type",
"sku": "[&1].sku",
"base_code": "[&1].base_code",
"name": "[&1].name",
"is_active": "[&1].is_active",
"language": "[&1].language",
"kalem_icerik": "[&1].attributes.kalem_icerik",
"@(0,attributes)": "[&1].attributes"
}
}
},
{
"operation": "default",
"spec": {
"\*": {
"dropdown_info": {
"urun_alt_grup_kod": {
"key": "alt_grup",
"value": "urun_alt_grup_kod",
"label": "alt_grup"
},
"marka_kod": {
"key": "marka",
"value": "marka_kod",
"label": "marka"
},
"urun_ana_grup_kod": {
"key": "urun_ana_grup",
"value": "urun_ana_grup_kod",
"label": "urun_ana_grup"
},
"renk_tonu": {
"key": "renk_tonu",
"value": "renk_tonu",
"label": "renk_tonu"
}
}
}
}
}

Input field can not be empty.

JOLT interface can be used instead of writing JOLT code. Interface provides operators as "Basic Shift", "Sort", "Array to object", "Object to array".

If JOLT interface wanted to be used by user, "Use mapping interface" checkbox should be selected.

5. Write Data to Omnitron

Settings are predefined for the Write Data to Omnitron and Read Data from Omnitron activities included in the integration flows. There is no need for users to edit these activities. Only timeout settings are displayed for these acitivities for informational purposes.

  • After making the necessary adjustments in the activities, clicking on Submit will save the relevant integration flow with the relevant arrangements.

After the activity settings are adjusted, the new Integration Flow appears as Passive on the Integration Flow List. The status of this flow must be turned on so that its status is set as Active and runs regarding its own settings.

6. Post-Script

If the client requires customized controls or adjustments for the response of Omnitron, they may choose the desired coding language and write Custom Scripts.

This screen mainly contains three parts; Input, Script, and Output.

Programing Script block is be entered to progress the script activity. Besides, entering the input JSON, and viewing the output by clicking Transform is not mandatory for the user. However, Input and Output blocks are suggested to be used in order to easify the controlling of written code in the Jolt Specification block.

Input Example

[
{
"sku": "3333333",
"price": 6040.0,
"price_discounted": 6040.0,
"price_list": "1",
"currency_type": "try",
"tax_rate": 8.0,
"retail_price": 7550.0
},
{
"sku": "2222222222",
"price": 0.0,
"price_discounted": 0.0,
"price_list": "1",
"currency_type": "eur",
"tax_rate": 8.0,
"retail_price": 0.0
},
{
"sku": "1111111111",
"price": 0.0,
"price_discounted": 0.0,
"price_list": "1",
"currency_type": "gbp",
"tax_rate": 8.0,
"retail_price": 0.0
}]

Script examples:

Example 1


class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Write output content
outputStream.write("Hello World!")

Example 2

class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Read input content
text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
#Load input json
obj = json.loads(text)
#Write output content
outputStream.write(bytearray(json.dumps(obj, indent=1).encode("utf-8")))

Example 3

class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Read input content
text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
#Load input json
obj = json.loads(text)
#Transform content
newObj = {
"Source": "Akinon",
"PriceList": obj[0]['price_list'],
"Name": "Entegrator"}
#Write output content
outputStream.write(bytearray(json.dumps(newObj, indent=1).encode("utf-8")))

Example 4

class TransformCallback(StreamCallback):
def __init__(self, flowFile):
self.flowFile = flowFile
def process(self, inputStream, outputStream):
#Read input content
text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
#Load input json
obj = json.loads(text)
#Transform content
index = 0
for item in obj:
item['newField'] = 'NewFieldIndex{}'.format(index)
item['tax_rate'] = item['tax_rate'] + 2
index+=1
#Write output content
outputStream.write(bytearray(json.dumps(obj, indent=1).encode("utf-8")))

Logs

It provides opportunities such as detailed log tracking of all integration flows in the project and the downloading of log files, facilitating the instant tracking of all integration flows.

The Integration Flow Logs page shows the log information of each execution of the relevant flow by listing them in rows.

In addition to the status of each execution of an integration flow (success, waiting, failed), this page displays detailed information such as the status of all end-to-end activities concerning the related flow (success, waiting, failed), the operator triggering the execution (system, user), the flow’s execution time, and the success rate of the transactions in the flow.

Click on Execution ID to examine the transaction-based log details in an execution of the integration flow. The flows of the transaction will be listed in the pop-up. Here, the Log File of transaction logs with Failed status can be downloaded for detailed control. Also filtering options (SKU or Status) can be used to filter the data shown.

The sub-flows in each integration flow are displayed with the boxes under the Activity-Based Status heading. If the relevant sub-flow has been successfully completed, it will be displayed in Green; if it has failed, it will be displayed in Red. If the log data in the sub-flow is needed to examine in details, the log file can be downloaded by clicking on the file icon on the relevant sub-flow box.

Note: The log file download function is not displayed for sub-flow activities with no logs.

Testing

It allows any of the integration flows in the project to be tested by running them end-to-end or triggering them manually as required.

Single or multiple triggering may be performed with file import using the Templates in the application. For multiple triggering, the relevant flow is selected and the file is downloaded from the Select Action field. After this template file is edited with the query parameter specified for flow, it is uploaded to the system and multiple triggering is performed.

Note: Triggering cannot be performed if the Status of the integration flow to be triggered is set to Off.

The parameters required for triggering must be entered by clicking on the RUN button next to the relevant integration flow.

After entering the parameters and clicking on RUN, triggering is performed for the relevant parameters. To view the current status of the triggering process in the relevant integration flow, the application queries every minute and displays the current status for the user.

As a result of the triggering, the user is provided with the Execution ID information for viewing the Log record. Clicking on this Execution ID opens a pop-up page that allows the user to access the log details.

Notification Settings

This menu allows the user to set the recipient information of the entered Alarm Conditions while creating a new integration flow.

More than one user can be defined for particular Integration Flows within the relevant Project, and information can be provided with various notification methods.

Notification Methods

  • Email

Although the application only supports Mail service for now, it will also support the PhoneCall, SMS and Slack Message services in the future.

You can add a new user by clicking the “+” button on the image above.

The notification method is selected by filling in the mandatory fields on the screen and clicking on Save&Close. Completing this process defines the Notification Settings.

Monitoring

This menu includes the functions that facilitate the monitoring of the Performance and Alarm Conditions for all projects created on Akinon Integrator and the integration flows within these projects. Functions:

  • Alarms
  • Performance

Alarms

This page listing is sent to users via the Alarm Notifications and added to the Notification Settings page when case-specific Alarm Conditions occur while the integration flow settings are being adjusted. It facilitates the viewing of detailed alarm notification content for the relevant Project and Integration Flow.

Select the Project and Integration Flow that you will be accessing for alarm details to bring up a detailed list of alarms below. When the limit value set according to a certain time period is exceeded while establishing the integration flow, the notifications are received with the selected notification method and the alarms are listed on the Alarm List page in the application.

Performance

It facilitates the monitoring of a project’s general status by offering detailed performance content for the relevant project.

Select the desired Project and Time Period in the filtering field. Upon selection, the performance metrics of the relevant project are listed.