Background

The purpose of this document is to provide an understanding of the information required by ONEiO in order to make a new endpoint type available in the service. It is highly recommended that the reader of this document review this Concepts & Components article located in the ONEiO Help Center to familiarize themselves with the terminology used within this document.

What is an endpoint type?

• Endpoint types are the technical components that handle all inbound and outbound communication with a single tool connected to ONEiO in an integration.
  
  
• Endpoint types can handle all communication methods like SOAP, REST, SFTP, etc.
  
  
• Endpoint types are also capable to use different authentication methods, attachment handling procedures and specific tool related features and limitations.
  
  
• For inbound traffic, there is a possibility to listen for web service calls from the connected tool (push), or poll changes incrementally from an interface (pull).
  
  

Different Kinds of Endpoint Types

• There are different kinds of endpoint types.
  
  
• There are tool specific endpoint types (e.g. ServiceNow, JIRA, and Zendesk), that vary depending on a different integration features of the tool.
  
  
• For example, ServiceNow has a variety of different options to use, compared to JIRA and Zendesk that have relatively limited/standard capabilities.
  
  
• More generic options are used when connecting a custom developed tool or "service bus" to ONEiO. In both cases, all the different features of the service are available to utilise.
  
  

Endpoint Types are always part of the ONEiO Subscription

• Endpoint types are always part of the subscription and are provided and maintained by ONEiO.
  All needed new features are always developed by ONEiO without any development cost to any customer. Having said that, users are able to configure different variables of the endpoint type in use to fulfil the particular use they need.
  
  
• Basic principle: when an endpoint type is available in ONEiO, there is no need for any ONEiO specific configuration on the connected tools side. ONEiO has all the means to adapt to the ways of the connected tool.

Information required for New Endpoint

What entities are planned to be integrated?

• It is essential to know what kind of entities are planned to be part of the integration.
• In most cases this determines the type of functionalities and APIs that can be used.
• Entities are typically the following:
  • Incident
  • Change Request
  • CMDB CI
  • etc

Inbound communication
(from the connected system into ONEiO)

To receive updates from the connected system, ONEiO needs to receive events. Communication can be initiated either from the connected system (Push), or ONEiO can be configured to query the changes from the connected system’s API (Pull). There is no clear guideline what is the preferred way. Normally the decision depends on the features the connected system provides and the use-case in hand. Rule of Thumb is that you should use the Push method, if you are implementing and event based integration (i.e. Incidents or Change Requests)

• Prerequisites - Push
  • Communication method (REST/SOAP/Other)
  • Example payload(s) of the messages that the connected system will send.
  • Examples should cover all the events that need to be covered in the "use case".
    (Create, update, status change, attachment(s), etc.)
    
    
• Prerequisites - Pull
  • In Pull method, ONEiO will poll an API for changed content in a short
    sequence (typically 30-60 seconds).
    
    
  • For ONEiO’s overlap intelligence to work in a robust manner, the following features need to be available:
    
    
    • There needs to be a way to query the API so that it will return only the
      entities that have been changed after a certain time. This information
      can be in the query URL or in the payload. For example:
      https://my.api.com/incidents?modifiedAfter=2020-01-01T10:12:22:123
      This query would return all Incidents that have been modified after Jan
      1st 2020 10:12:22:123AM.
      
      
    • The returned entities must contain and unique id element AND an
      element that tells when the entity has been edited the last time (in the
      earlier query “modifiedAfter”)
      
      
    • The authentication method in the calls normally follows the same way defined
      in Outbound communication. Please provide ONEiO details about this in case
      it needs to be different.

Outbound communication
(from ONEiO to the connected system)

ONEiO will always adapt to the functionality of the connected system.

Please define the following details:

• Authentication. What kind of authentication mechanism the connected system’s API
  uses.
  • Communication method (REST/SOAP/Other)
  • Example payload(s) of the messages ONEiO needs to send to the connected system.
  • Examples should cover all the events that need to be covered in the "use case".
    • (Create, update, status change, attachment(s), etc.)
      
      

About Message Examples:

• Postman collections or similar are the most efficient way since they contain all the needed header and other information.
  
  
• If the API uses multi step (like OAuth2) authentication, please provide an example of
  that functionality also.
  
  
• In the case of SOAP, wsdl’s are useful but not sufficient since they lack mandatory
  attribute content.

Additional Resources

• API documentations and guidelines are always welcome, but not sufficient. The
  reason for this is that the best way to use these APIs often depends on the use case
  in hand. That is why we need to have the concrete samples of the messaging in
  detail to make the endpoint type available in the most efficient way.
  
  
• Accessible sandbox environments are also useful to have available while testing out
  the configuration and validating the defined functions.

How to Proceed

You can use the attached Worksheet to collect the info the above information about the New Endpoint Type. Please send this information to our Customer Success Team (sales@oneio.cloud), so that we can continue the discussion.