WEBCON requirements for integration with WEBCON BPS

   PDF version

• Introduction

• Requirements towards the Customer and the Integrator

• General information solution requirements

• Initial data import into WEBCON BPS

• Exemplary description of integration message

 

Introduction

Document description

The document sets out design and technological WEBCON BPS requirements for integration of the WEBCON BPS system with external systems. In the doument the terms: the Customer and the Integrator are used. In the respective cases when the integration process does not involve a third party (business entity), the terms the Customer and the Integrator refers to the same entity (the Customer). 

Requirements towards the Customer and the Integrator

Below you can find some enquiries related to the system and requirements pertained to the breakdown to the respective project lifecycles.

Sales cycle requirements

Key questions to the Customer’s ERP:

• What systems will be integrated with WEBCON (ERP, HR, etc.)?
• What integration solution method with external systems will be employed to each system?
• Which form values should be transferred to external systems?
• Does the Customer have its interface prepared?
• Is the Customer able to deliver data transfer documentation?
• Are integrations with other systems planned?

Study cycle requirements

• The Integrator takes part in analytical integration talks.
• The Customer/Integrator verifies the data structure and data quality (whether there is a unique key or data is not repeated etc.)
• While carrying out the study, the scope of the data required for implementation (see chapter “Examples of Views”) will be specified.
• The Customer/Integrator is responsible for the delivery and quality of the data.
• The data should be normalised (e.g., separate Views with Customers and bank accounts combined via Customer ID relation).

Configuration cycle requirements

• At the initial configuration phase, the Integrator delivers the “Hello World” interface in order to check communication process and  inspect whether possible authentication is required.
• Along with the web service or procedure the Integrator delivers an exemplary message invocation together with expected feedback message (either “an error” or “a success”). An example of the  message description  is presented later in the document.
• The Integrator delivers both the web service and its documentation.
• When installing DEV/TEST/PROD WEBCON, it is recommended to create dedicated accounts available for each of the installations. Such accounts should have non-expiring passwords.
• No data in the source system will result in no data in the WEBCON BPS system.

General integration solution requirements

Below you can find a general list of WEBCON integration recommendations and requirements taking into account various integration types.

Requirements towards the Customer/Integrator

1. Views

• WEBCON expects delivery of a view/table (dictionaries based on SQL procedure are not enhanced).
• The view/table should be responsive (the request “Select top 1000 * from table_name” should provide results within less than a second)
• The account delivered by WEBCON should be equipped with a read view privilege
• The view/table should be reliable
• The view/table should have a unique indexed ID
• MS SQL, Oracle technologies as standard
• The views delivered by the customer should be outside the contents of WEBCON BPS databases.

2. Examples of views

View of Customers

Column:

• ERP_ID - unique ID applied to the entire data set, required
• NAME - required
• NIP [TAX IDENTIFICATION NUMBER] - required
• COUNTRY - optional, two-digit country code
• CITY - optional
• ADDRESS- optional
• ZIP-CODE - optional
• CUSTOMER_ASSISTANT - optional, format domainlogon or UPN

Bank accounts

Columns:

• ID - unique ID applied to the entire data set, required
• ACCOUNT_NUMBER – account number in IBAN format, required
• ERPID_ACCOUNTS - customer id, required

Cost centre

Columns:

• ID - unique ID  applied to the entire data set, required
• COST CENTRE _NUMBER-  Cost Centre numbers, displayed in the form, required
• NAME – Cost Centre name, optional

3. Web Service integration (WEB Service)

Architecture: General provisions

• Communication streams - mono directional data synchronization stream will be employed. It ensures data transfer from the WEBCON BPS system to ERP when succesful workflow reprocessing in the WEBCON BPS system.
• Communications mode - synchronous communication question-answer type. In this mode one of the parties (workflow) sends an enquiry to the other party (external system) and expects an answer. Any potential communication loss incidents do not affect data consistency. 
• Message buffer - WEBCON does not envisage workflow message-buffering. Communication will be triggered upon workflow completion. When the system is not given any answer, or receives "an errr" message, on the user's screen a message will be displayed. 

4. WEB Services of the Customer

• The message should allow for saving WEBCON WFD_ID and returning the  domain system ID (it refers to the messages on the entry into the domain system).
• Error message feedbacks should be clear for the end user. In case of any exception, error messages will be displayed for the user in the form.
• WEBCON requires the use of synchronous communication as standard
• The entry should be transactional (it is fully successful or not). A single message should contain a set of data (e.g., for entering an invoice, such message should hold both the header data and breakdown data).
• Authentication and entry will be proceeded within the respective service account (such account should have a non-expiring password).
• A standard invocation is served by WEB Service at a single nesting level.
• SOAP 1.2 version is enhanced.
• It is recommended to trigger and retrieve an interface response within time less than 2 seconds. The maximum time for the interface response may be 5 seconds. Long time for the interface response will directly affect the quality of the user form.

5. Integration with data bus

• Errors are handled by data bus.
• The data bus withdraws changes when errors occur.
• WEBCON assumes that the data bus is transparent.
• WEBCON is not responsible for data bus configuration (end-point configuration; interface mapping).
• Communication should be synchronous.
• The data bus is responsible for sequencing messages, redoing messages.

6. Integration with the use of SQL procedure

• WEBCON BPS is equipped with a standard action for invoking the procedure.
• WEBCON uses the procedure to enter data (not in the form of dictionaries).
• The procedures originating from external databases require an additional study.

 

Integration solutions offered by WEBCON BPS - examples

Below you can find examples of implementing WEBCON BPS integration system with external systems. The examples illustrate data entry into an external system and data downloading from an external system. The solutions set out below may be implemented with the use of the technologies described later in the document (WEB Services, SQL views, SQL procedures).

1. Synchronous data entry into external system

The synchronous method of entering an element into an external systems is the most common and recommended method of integrating WEBCON BPS system with external systems. The method is ilustrated on the example of entering an invoice document into an external system. 

An invoice is registered and approved in the WEBCON BPS system. In the "Accounting Verification" step an invoice entry into the external system is invoked. The user invokes the entry by using the WEBCON BPS system. 

Such entry is made by invoking a synchronous WEB Service at the "Entry into ERP" path. WEB Service transfers given invoices to the external system and in response the ID of a created element is returned. When the WEB Service is invoked correctly, the invoice in the BPS system automatically goes to the final step. 

Such method ensures data consistency across the systems. When selecting said method one should take info account in particular the time-span of the WEB Service invocation. 

 

 

2. Asynchronous data entry into external systems

A cost invoice is registered and approved in the BPS system. In the “Accounting Verification”  step an invoice entry into the external system is invoked. The user invokes the entry by using the BPS system.

Such entry is carried out asynchronously by employing two WEB Service integration methods. The first method is used for transferring invoice data to ERP; the second one serves for collecting information whether the respective invoice has been created correctly in the system.

At the path “Entry into EPR " the user invokes an invoice data transfer. The web service does not return information about the correctness of document creation in ERP, only about the status of accepting the message.

In the WEBCON BPS system the invoice goes to WAITING FOR RESPONSE step. In this step the system automatically and periodically invokes the WEB Service, checking correctness of the entry. Upon receipt of the information on the document number, the invoice goes to the final step. In principle, such solution takes up a huge chunk of time. Additionally, the end user is not given a response from the domain system when completing its task in the WEBCON BPS system.

 

 

3. Downloading dictionary data

Downloading data from SQL view

An external system provides data via SQL views. A delivered view is used in WEBCON BPS system as a data source. The view is polled on demand (online) – when the user selects a value from the dictionary in the WEBCON BPS system.

This integration solution method is frequently applied and recommended. It ensures fixed access to the updated data. When selecting this method, one should take into account in particular the time-span in which the views respond as it directly translates into the operational speed of the user interface (form) in the WEBCON BPS system.

 

 

 

Downloading data - WEB Service polling

The external system provides data via WEB Service. WEB Service is available to the BPS system and used as a data source. WEB Service is polled on demand -  when the user selects a value from the dictionary.

This integration method ensures data updates. When selecting this method one should pay attention to the time-span in which the web service is invoked as it transfers directly into WEBCON BPS access to data.

 

 

 

Downloading data - data dump into SQL indirect table

An external system provides data via WEB Service. In view of a vast amount of data, the data returned by the domain system is synchronised by WEBCON dedicated dictionary database in a dedicated table. Data synchronisation is carried out by periodically (e.g., once per 24h) invoked web service and the returned data is recorded in the table. The table is used as a WEBCON BPS data source and polled each time the user selects a value from the dictionary.

Such integration solution method guarantees fast data access. A weakness of the solution is the periodic synchronisation and the risk that the data in the table may be out of date.

 

 

4. WEBCON Services provided by WEBCON

• WEBCON holds a standard WEB Service based on REST technology
• WEBCON may deliver a dedicated service in SOAP, REST technology. Such dedicated service requires an additional study.
• WEBCON does not provide web services on servers other than  WEBCON BPS installations
• More information within this respect you may find at: https://developer.webcon.com/docs/rest-api/
• Current addresses of standard WEBCON BPS web services (BPS Web API): [BPS Portal URL]/api -> e.g.: https://www.mycomapny.com/webconbps/api
• WEB Service REST allows for, among others,
  • creating new instance in WEBCON BPS
  • editing the existing instance  
  • shifting the existing instance to further step
  • adding an attachment
  • downloading an attachment
  • deleting the existing instance.

Initial data import into WEBCON BPS

• General approach to the initial data import is described in a separate document: Data_Migration.docx
• Files imported into WEBCON BPS must be equipped with an extension.
• WEBCON does not recommend an import of files larger than  100 MB.
• The format of the data delivered by customers must be in line with the .NET standard
  https://docs.microsoft.com/pl-pl/dotnet/standard/base-types/formatting-types
• The data delivered by customers should be in a tabular format.
• The data delivered by customers should be standardised (uniform data format, no text values in the data, one data type per column etc.).
• The delivered view must be responsive and response immediately  (“Select top 1000 * from table_name” enquiry should be proceeded less than a second).

 

Exemplary description of integration message

 

Business message	Invoice data entry into ERP
Action to be processed by the source	Complete data transfer to ERP
Action to be processed by the Contractor	Data entry into the system. An error or a success feedback
Source system	WEBCON
Target system	<ERP name>
INPUT PARAMETERS
Message field name	Workflow form field	Message field type	Required	Comments
REGISTRATION_DATE	Registration date (Date field)	DATE	Y	Document registration date
REGISTRANT	Registrant (person or group)	STRING	Y	Registrant (domain login or name)
DOCUMENT_NUMBER	Instance number (text field)	STRING	Y	Automatically assigned upon registration e.g. F/2019/01/0001
WORKFLOW_ID	Instance identifier	INT	Y	Workflow instance identifier
INVOICE_NUMBER	Invoice number (text field)	STRING	Y	Invoice number. Filled in manually by registrant
RECEIPT_DATE	Receipt date (date field)	DATE	Y	Date of filling in by registrant. Current date by default
ISSUANCE_DATE	Issuance date (date field)	DATE	Y	Date filled in by registrant
SALES_DATE	Sales date (date field)	DATE	Y	Date filled in by registrant
PAYMENT_DATE	Payment date (date field)	DATE	Y	Date filled in by registrant
CUSTOMER_ID	Customer (choice field)	INT	Y	Customer ID from ERP
CURRENCY	Currency (Choice field)	STRING	T	Currency code
PAYMENT_METHOD	Payment method (choice field)	STRING	Y	Payment method selected from the SharePoint list. The list of available values will be delivered by the Client.
NET_AMOUNT	Aggregated net amount (floating-point number)	DECIMAL	Y	The amount filled in manually by registrant or OCR
GROSS_AMOUNT	Aggregated gross amount (floating-point number)	DECIMAL	Y	The amount filled in by registrant or OCR
ACCOUNT_NUMBER	Bank account number (choice field)	STRING	N	Field filled in by registrant
CURRENT_USER	Current user (person field)	STRING	Y	Person who does the task in the "Current user" step. By default is a current user at the OCR verification step.
ASSOCIATED_INVOICE_ID	Associated invoice (choice field)	INT	N	An employee may indicate an associated invoice registered in the workflow system. Invoices of the respective customer will be hinted
COST_ASSIGNMENT	Cost assignment (list)	ARRAY	Y	A table designed for cost allocation
List - Cost assignment
COST CENTRE	Cost centre (choice field)	STRING	Y	Selection of the cost location from the dictionary delivered by the client. To be specified whether the client will implement the dictionary common for both systems.
OWNER	Owner (person or group)	STRING	Y	Cost owner
DEPARTMENT	Department (choice field)	STRING	Y	Field filled in automatically according to the owner
LIMIT	Limit (floating-point number)	DECIMAL	Y	Field filled in automatically according to the owner
NET_AMOUNT	net amount (floating-point number)	DECIMAL	Y	Amount filled in manually by registrant or current user
OUTPUT PARAMETERS
Form fields	Type	Source	Required	Comments
STATUS	INTEGER		Y	Operation status (0-error,1-success)
INFO	STRING		N	Error message