Upload
buique
View
213
Download
0
Embed Size (px)
Citation preview
E N G H O U S E S Y S T E M S L I M I T E D
E N G H O U S E N E T W O R K S D I V I S I O N
A S S E T M A N A G E M E N T G R O U P
API INTERFACE USER GUIDE
Training Guide
Document ID: TRG167
Revision: 4.00
Lifecycle Status: Issued
Owner: Technical Architecture Team
Project: GNO
PROPRIETARY INFORMATION: The information contained in this document is the property of Enghouse Systems Limited. Except as specifically authorized in writing by Enghouse Systems, the holder of this document shall keep all information contained herein confidential and shall protect same in whole or in part from disclosure and dissemination to all third parties.
Associated DocumentsDocument ID TitlePER3 NETONE BASELINE – INBOUND APIPER9 NETONE BASELINE-GENERIC OUTBOUND APIS-PRODUCT EXTENSION
REQUIREMENT
Document Revision HistoryVersion Date Author Details0.00 24-JUN-2002 Chi Yau Initial Version0.01 05-JUL-2002 Chi Yau First Draft0.02 08-JUL-2002 Chi Yau Change to inbound API Interface0.03 10-JUL-2002 Chi Yau Minor changes.0.04 11-JUL-2002 Chi Yau Upgrade DMS release.0.05 12-JUL-2002 Chi Yau UPDATE TITLE FROM TRAINING TO USER.0.06 12-JUL-2002 Chi Yau Second Draft.0.07 16-JUL-2002 Chi Yau Changed from inbound to API Interface0.08 17-JUL-2002 Chi Yau Added Outbound APi Interface0.09 23-AUG-2002 Huw Davies Amended header and other minor
changes1.00 23-AUG-2002 Huw Davies Issued1.01 09-MAR-2005 Michael Dunkley Details on automating the inbound and
outbound interfaces and managing them1.02 15-MAR-2005 Michael Dunkley Minor changes following review by Bryn
Harris1.03 18-MAR-2005 Michael Dunkley Corrected syntax for java permissions,
remote directory set up2.00 18-MAR-2005 Michael Dunkley Issued to client2.01 11-JUL-2005 Michael Dunkley Added java read permissions req'd for
local inbound interface3.00 14-MAY-2007 Chi Yau Issued.3.01 30-JUN-2008 Richard Hopkins Update to add missing details3.02 09-OCT-2008 Richard Hopkins Updated3.03 04-AUG-2010 Richard Hopkins Some updates3.04 17-AUG-2010 Dominique Adams Screenshots updated to V63.05 27-MAY-2011 Richard Hopkins Updated for Implementation Pack Issue3.06 23-MAY-2012 Richard Hopkins Enghouse format applied3.07 24-MAY-2012 Andrew Watkins Spelling and grammar changes, removed
reference to 'Gamma'.3.08 24-MAY-2012 Andrew Watkins Added related document IDs.3.09 30-JUL-2012 Andrew Watkins Updated screenshots to v73.10 01-AUG-2012 Neal Williams Updated header/footer4.00 01-AUG-2012 Neal Williams Updated document title
Reviewers
Reviewer Name Reviewed Date Reviewed Version Review StatusHuw Davies 23-AUG-2002 0.08 CompleteAndrew Watkins 24-MAY-2012 3.06 Complete
Please Note – Do not manually edit any details above this line. This should be undertaken through the Document Control System only!
Table of Contents
1. Glossary of Terms..........................................................................................................................7
2. Course Objectives..........................................................................................................................8
3. Overview........................................................................................................................................9
3.1. Net Transact components......................................................................................................9
4. Interface Managers......................................................................................................................10
4.1. The Different Types of Managers.........................................................................................10
4.2. Controlling the Managers....................................................................................................11
4.3. Manager Configuration........................................................................................................11
5. Overview of API Inbound Interface..............................................................................................13
6. Screens of the API Inbound Interface..........................................................................................14
6.1. Interface Transaction Screen...............................................................................................14
6.1.1. The Basic Setup............................................................................................................15
6.1.2. The Prompts Tab..........................................................................................................16
6.1.3. Mappings Tab...............................................................................................................19
6.1.4. Default Values Tab.......................................................................................................24
6.1.5. Users Tab.....................................................................................................................26
6.1.6. Extra Validations Tab...................................................................................................27
6.2. File Upload Configuration Screen........................................................................................28
6.2.1. File Details Tab.............................................................................................................28
6.2.2. Column Mapping Tab...................................................................................................29
6.2.3. Users Tab.....................................................................................................................30
6.3. File Upload Screen...............................................................................................................31
6.3.1. File Type Tab................................................................................................................31
6.3.2. Upload Files Tab...........................................................................................................32
6.4. Interface Data Screen..........................................................................................................33
6.4.1. Types Tab.....................................................................................................................33
6.4.2. Data Entry....................................................................................................................34
6.5. Interface Records Screen.....................................................................................................34
6.5.1. Transaction Data Tab...................................................................................................35
6.5.2. Errors Tab.....................................................................................................................37
6.5.3. Interface Data Tab.......................................................................................................38
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.6. Error Correction Screen.......................................................................................................38
6.6.1. Error Record Tab..........................................................................................................39
6.6.2. Interface Data Tab.......................................................................................................40
6.7. Interface Tables Screen........................................................................................................41
6.7.1. Interface Tables Tab.....................................................................................................41
6.8. Archive Screen.....................................................................................................................42
6.8.1. List View Tab................................................................................................................42
6.8.2. Record View Tab..........................................................................................................43
6.8.3. Error Message Tab.......................................................................................................43
6.9. Application Queries Screen..................................................................................................44
6.9.1. Query Tab....................................................................................................................44
6.10. Other Screens..................................................................................................................45
7. Automating the API Inbound Interface........................................................................................46
7.1. File Locations Screen............................................................................................................46
7.1.1. Local Directories Tab....................................................................................................46
7.1.2. Remote Directories Tab...............................................................................................47
7.2. File Naming Conventions Screen..........................................................................................49
7.3. Automated Interfaces Screen..............................................................................................50
7.3.1. Definition Tab..............................................................................................................50
7.3.2. Scheduling Tab.............................................................................................................52
7.3.3. Locations Tab...............................................................................................................53
7.3.4. Inbound Filters Tab......................................................................................................54
7.3.5. File Naming Tab...........................................................................................................55
8. Managing the Automated Interfaces...........................................................................................56
8.1. Interface History Screen......................................................................................................56
8.1.1. Interface Runs Tab.......................................................................................................56
8.1.2. Interface Run Data Tab................................................................................................57
8.1.3. Interface Run Messages Tab........................................................................................57
8.2. Calculating the Next Run Date.............................................................................................58
8.3. Scheduling an Interface Run Immediately...........................................................................58
9. Overview of API Outbound Interface...........................................................................................59
10. Screens of API Outbound Interface..........................................................................................60
10.1. Interface Generation........................................................................................................60
10.2. Application Queries Screen..............................................................................................61
Page 5 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.3. File Download Configuration Screen................................................................................62
10.3.1. Outbound Transaction Tab..........................................................................................62
10.3.2. Fields Tab.....................................................................................................................63
10.3.3. Restrictions Tab...........................................................................................................64
10.3.4. Users Tab.....................................................................................................................65
10.3.5. Preview Tab.................................................................................................................66
10.4. Download File Screen......................................................................................................67
10.4.1. Export Requests Tab....................................................................................................67
10.5. User Requests Screen......................................................................................................68
10.5.1. User Request Tab.........................................................................................................68
10.5.2. Errors Tab.....................................................................................................................69
11. Automating the API Outbound Interface.................................................................................70
11.1. File Locations Screen........................................................................................................70
11.1.1. Local Directories Tab....................................................................................................70
1.1.1. Remote Directories Tab...............................................................................................71
11.2. File Naming Conventions Screen......................................................................................72
11.3. Automated Interfaces Screen..........................................................................................73
11.3.1. Definition Tab..............................................................................................................74
1.1.2. Scheduling Tab.............................................................................................................75
11.3.2. Locations Tab...............................................................................................................76
11.3.3. Outbound Filters Tab...................................................................................................77
11.3.4. File Naming Tab...........................................................................................................78
Page 6 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
1. Glossary of Terms
Term Description
LOV List of Values
API Application Programming Interface
CSV Comma Separated Value
DTD Document Type Definition
XML Extendable Mark-up Language
Page 7 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
2. Course Objectives
The purpose of this course is as follows:
To provide the super user / administrator with the correct knowledge to complete the NetTransact configuration of NetOne.
At the end of the course, the user will be able to:
Locate the relevant Gamma NetOne screens. Configure inbound/outbound transactions. Control the interface managers. Understand how to use the error correction module.
Page 8 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
3. Overview
NetTransact allows the NetOne application to interact with external applications or systems. The module provides NetOne with both inbound and outbound interfacing, allowing the import of data from, and the export of data to, external applications.
NetTransaction can be used for different functions:
To support automatic data synchronisation between third party applications and NetOne. E.g., creation of site and network element data automatically that have been created in a radio planning tool.
To support off-line data collection via hand-held terminals for transaction processing, e.g., goods receipts, stock-taking, data take-on etc.
To support bulk data loading from files prepared with other products (Excel, SAP, Oracle Financials etc) for data take-on and migration.
3.1. Net Transact components
The module is split into several different functional areas:
Interface ManagersThe managers are the ‘engine’ which drives the interface module, allowing inbound data and outbound data to be processed.
Transaction DefinitionConfiguration of the mechanics of the data processing takes place here.
Inbound FilesThis area covers management of data coming into the system.
Outbound FilesThis area covers the management of data going out from the system.
Automatic InterfacingAllows the integration and automation of inbound and outbound data processes.
Error CorrectionWhere the management of errors in the data occurs.
Page 9 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
4. Interface Managers
The core processes of Net Transact are the interface managers. These can be accessed from the API tab of the admin menu. The manager screen allows the basic configuration of the manager processes, how often they run, if they are on or off etc.
The screen looks like this:
The managers handle the interfacing of data, automated interface processing, error correction, email generation and housekeeping.
4.1. The Different Types of Managers
A manager is an Oracle job which runs in the database at regular intervals, controlled by the parameters in the manager module. Each manager has a different function within NetTransact, as follows:
Map Managers control where the inbound data goes in the application, e.g. site data must end up in the sites table.
Process Managers provide validation of data, generating error messages to inform the user of any problems or validation failures. An example of a validation failure would be attempting to use a site ID which did not exist in the system.
The Upload Manager controls the process of loading a datafile and submitting it into the interface.
Housekeeping is a process which removes unwanted historical data. It has an additional configuration screen to manage the removal of different types of data from the system.
The Mail Manager is responsible for sending emails out via SMTP. In order to send emails, a correctly configured SMTP server must be available.
The User Request Manager governs the creation of outbound data files.
Page 10 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
The Error Correction Managers allow the user to correct data which has failed validation and to resubmit it to the interface for processing.
The queue number is used to handle the map and process managers. The queue number is only applicable to these as there are three map managers and three process managers. For the other managers only a single process is necessary.
The queues allow more than one interface to be processed simultaneously. Queue 0 is the error manager queue and exclusively handles data which has been corrected and resubmitted to the system. Queues 1 and 2 allow separate interface processes to be run at the same time.
4.2. Controlling the Managers
Managers may be off or on. Status STOP means the manager is off, and will never run, regardless of any other configuration settings.
To turn a manager on or off, use the check box at the left of the screen. Check the tickbox of the manager you want to alter, then press the START, STOP or RESET button at the bottom of the screen.
The start button will attempt to start the manager if it is currently stopped.
o Starting a manager which is already running has no effect.
o When a manager is in the process of starting, the status will display SUBR – submitted to run.
o When the manager is running, the status will change to RUN and the description will alter to display the time the manager was started.
The stop button will attempt to stop the manager if it is already running.
o Stopping a manager which is not running has no effect.
o The status will change to STOP once the manager has stopped.
o There are some circumstances which prevent a manager from stopping immediately. In this case, the status will display SUBR until the job has stopped. This happens when the manager is still processing some data. For example, if a process manager is currently checking some data and a stop request is received, it will stop after the current process has finished.
There are two other buttons at the bottom of the screen, “Select All”, and “Un-Select All”. These simply provide a quick method of checking or unchecking all the checkboxes present on this screen.
4.3. Manager Configuration
Each manager is configured to run at specific intervals. The interval can be changed by the system administrator to reflect the needs of the system. For example, emails could be generated once per day, overnight so that they are delivered to the users inboxes before they arrive at work the next
Page 11 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
day, or, if a faster response is required, the email manager could be configured to run every 5 minutes.
The unit, unit type and description fields denote how often the manager runs.
o Unit is a positive integer entry between 0 and 99999
o Unit type is one of DAY, HOUR, MIN or SEC
o Description is a non-enterable field for the unit type lookup
The date/time field allows a manger to be run at a specific time.
o This field is a date/time entry which allows you to enter a time for the process to execute in the format DD-MON-YYYY HH:MI:SS, eg., 01-JAN-2020 12:00:00
Maximum retries tells the map and process managers to stop attempting to process a set of data once it has failed a certain number of times, for example, attempt to process 50 times then stop.
o Retries must be between 0 and 99999 inclusive
Page 12 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
5. Overview of API Inbound Interface
This section is intended as a user guide for theNetOne API Inbound Interface, and includes information about how to configure the API Inbound Interface. This document is based on the Product Extension Requirement document called ‘Gamma_GHO_PER0003_0.01’.
The API Inbound Interface provides a mechanism for the NetOne application to interface with other external applications. A combination of user instructions and examples will be provided in the document to explain the API Inbound Interface functionality.
This section is intended for NetOne Administrators with knowledge of the Oracle SQL programming language.
The Interface File represents the physical interface file e.g. a CSV file. This interface file does not form part of the API Inbound Interface. The interface file is generated by an external application or manually by hand e.g. bar code readers, handheld devices, third party systems, spreadsheets etc..
The Generic Interface Table is a holding area within the NetOne application which stores all incoming data whilst it is being processed. The generic interface table holds transaction data without having knowledge of the data definition e.g. format, length etc i.e. raw data.
The Interface Tables represent the specific interfaces e.g. SITES_INTERFACE, WORKS_ORDERS_INTERFACE etc. and are used as an intermediate process step between the generic interface table and the application module tables.
Page 13 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
The Gamma NetOne Tables are used by the NetOne Application.
6. Screens of the API Inbound Interface
The API Inbound Interface Module consists of the following screens:
1. Interface Transaction Screen
2. Interface Data Screen
3. Interface Records Screen
4. Interface Manager Screen
5. Error Correction Screen
6. File Upload Configuration Screen
7. Upload File Screen
8. Interface Tables Screen
9. Archive Screen
10. Application Queries Screen
11. Download File
12. File Download Configuration
13. Automated Interfaces
14. File Locations
15. File Naming Conventions
These are accessed from the APIs tab of the NetOne Administration menu:
Page 14 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.1. Interface Transaction Screen
An interface transaction is a template describing how to process and load data into NetOne.
A transaction consists of several parts:
A series of prompts, or column definitions, which describe the data being submitted into the system.
A set of mapping rules which instructs the system where to place the data from the prompt definitions.
Additional default values and validation rules.
The interface transaction screen can be found on the API subtab of the Admin Menu, using the button “Interface Txns”.
6.1.1. The Basic Setup
The Transaction Types tab is shown in the below screenshot:
On the main tab of the interface transactions the following fields are displayed:
Txn Type - The identifying UDK for the transaction, this is a mandatory entry.
Description - A brief description of the transaction.
Page 15 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Ext Txn Type - An entry which is passed through to the interface data which allows identification of the origination of the data. For example, if data is being imported from SAP, then the transaction could have a SAP identifier in this field.
Active - Checked when the transaction is available for use. If unchecked, the transaction will not be displayed in screens where it can be selected.
Archive - If checked, all data processed by the transaction will be copied to the archive tables.
Realtime - If checked, the data will be process immediately by the system once it is entered. This checkbox is used in conjunction with the API data entry screen and is not for use with datafile loading.
Notes - Any other pertinent information, as in the above example a version number and initials of the author.
6.1.2. The Prompts Tab
Prompts define two important items for a transaction. If the data for this transaction is being captured by a hand held terminal, or being entered in the interface data screen, then these prompts are the on-screen field labels which allow the user to put the appropriate data in the correct place.
If the data is coming into the system via a CSV file from another application or as a migration dataload, then the prompts define the columns of data (i.e., like a spreadsheet).
Figure 1 - Prompts tab
The following configuration defines each prompt:
SEQ No - Enter a unique sequence number between 1 and 255 for the prompt. The sequence number will decide the display order of the prompts on the Interface Data Screen, and the column order for inbound data files.The sequence number is mandatory, must be unique and is an integer between 1 and 255 inclusive.
Page 16 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Prompt - Enter the prompt label that will be displayed on the Interface Data Screen. Labels are not used for data files but are required as it shows what is contained in each column. The prompt label is mandatory.
Next Prompt – When a handheld (or the interface data screen) is being used to capture the data, this value determines to which prompt the cursor will move after entering the current field. Enter the sequence number of the next prompt.
The last prompt of the transaction normally returns the user to the first prompt on the next new record, when the transaction is being used in the interface data screen. Next Prompt is a mandatory entry.
Data Type - Enter the prompt data type. One of:
o ‘A’ represents alphanumeric characters
o ‘M’ represents Model
o ‘N’ represents numeric data
Min Length - Enter the minimum length of the prompt. A non-zero value will make the prompt value mandatory.
Max Length - Enter the maximum length of the prompt value.
X Pos – The X coordinate position on the interface data screen where the prompt will appear.
Y Pos – The Y coordinate position on the interface data screen where the prompt will appear.
Copy Previous - When checked this will copy the previous record value entered on the Interface Data Screen. This will help to minimise repetitive input of the same data, for example if you are entering data for the same site, and the first prompt was the site code, checking this box will make the prompt automatically pick up the value from the last record you entered, thereby saving you time entering it again.
Pattern Match - Enter the prompt format mask. This will enforce the format of the data input. For example: -
o ‘#’ (Pound sign) represents numeric mask
o ‘.’ (Period sign) represents alpha mask
o ‘%’ (Percentage) represents zero to many characters
o ‘_’ (Underscore) represents only one character
o ‘:’ (Colon) represents range of values
Page 17 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
o ‘,’ (Comma) represents separate masks
o ‘!’ (Exclamation) represents reverse mask
Pattern match defaults to ‘%’ meaning any value is valid.
On-Line SQL – This is an LOV list of all application query entries defined as type LOV.A prompt can be made into an LOV lookup instead of a regular free-format entry. The LOV lookup is defined in the application query screen, the UDK of that query is selected in this field. The prompt will then be displayed as an LOV in the interface data entry screen, with the data selected by the SQL statement from the application query.
Validate SQL – When this checkbox is checked it instructs the data entry screen to validate the data entered by the user against the On-Line SQL LOV list. If the data is not in the list, it will not be allowed.
Descr. LOV SQL – Similar to the On-Line SQL LOV, this value is also an application query SQL statement. It will use the value in the prompt to lookup another value in the database, for example, a description, and display that value on the interface data entry screen.
ASCII SQL – This is not currently used for the inbound interfaces. Used to create the external validation file for use on the handheld devices. The validation file will be stored in ASCII. The validation file has an extension of ‘inp’. Please see the Mobilis instruction manual for more details.
Override – When checked the user may override the prompt value validation, even if the Validate SQL flag is checked. This is used when it is useful for the user to be able to pick a standard value from a list, but to be able to also enter a value which is not defined in that list.
Not in File – When checked prompt validation not in validation file.
Validation File – Reference to directory path and validation filename to be used for validation. This is only used on the hand held device and is detailed in the Mobilis documentation.
If Data is – The next three prompts work together to provide some logic for jumping to a prompt which is not the Next Prompt value.
Enter a set operation for prompt e.g.: -
o ‘!=’ represents not equal
o ‘<’ represents less than
o ‘<=’ represents less equals to
o ‘<>’ represents not equal to
o ‘=’ represents equal to
Page 18 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
o ‘>’ represent s greater than
o ‘>=’ represents greater equal to
Pattern – Enter pattern using match pattern convention above. The pattern will be compared using the set operator against the prompt value.
Go To – The sequence number of the prompt to navigate to after resolving the ‘If Data is’ and ‘Pattern’ columns.
Dynamic Prompt File – Enter the directory path and name of file containing other prompts.
Archive Column – Enter the column to be archived. When this is empty no archiving of this prompt will take place.
Validate Button – Validate the prompt configuration including:
o The prompt sequence number should start with 1 and normally there should be no gaps between the sequence numbers unless you want to ignore specific columns of data.
o Maximum number of sequence numbers is 255.
o The next prompt sequence number should exist as a prompt sequence number.
o The ‘Go To’ sequence number should exist as a prompt sequence number.
6.1.3. Mappings Tab
The Mapping tab allows the mapping of prompts onto the interface table columns. This is a set of instructions to the interface mapping process telling it which field to put each prompt value in, and how to modify that data using SQL expressions if required.
Figure 2 - Mapping tab
The tab contains two blocks. The top block determines the process and mapping order for the transaction and the lower block defines the detailed mapping instructions.
The top block holds the process and mapping order, and the action to be performed:
Page 19 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Process Seq. – Enter a unique number for the data set e.g. 1, 2, 3, 4, 5 etc. In the case of complex data sets this will determine the order in which the data set will be processed. For example, given a transaction which creates sites and network elements, the site must be created before the element can be added to the system, therefore the site mapping must occur before the network element mapping.
Map Sequence – Enter the unique sequence number of the data set e.g. 1, 2, 3, 4, 5 etc. The map number allows multiple inserts into different interface tables from the same data source, for example, creating two network elements from the same data.
Name – Defines the interface to be used. Enter the name of the interface or alternatively use the LOV to populate the Name and Table Alias columns.
Table Alias – Non-enterable, this is the table description for the interface table name.
Action – Enter action for the data set. Must be one of the following:
o ‘INS’ instructs the interface to attempt to create data in NetOne
o ‘DEL’ instructs the interface to attempt to delete data from NetOne
o ‘INUPD’ instructs the interface to insert data in NetOne if none exists already, or update it if it does
o ‘UPD’ instructs the interface to update data in NetOne
In all cases if it is not logical to perform the operation, i.e.update a row that does not exist, insert a row which already exists etc. an error message will be raised.
The lower block holds detailed instructions for each of the mappings:
Line No. – Enter a unique sequence number for displaying the mapping record.
Column Name – Enter the interface table column name or use the LOV to select one from the list of columns available for the selected interface. This is the column which will receive the data in the specified prompt, or from a derived SQL expression or fixed value.
Column Description – The column description is derived from column name and is not enterable.
Prompt – Enter the prompt number from the prompt screen if the data is to be placed directly into the column name used for this mapping. If the column is to take a derived or fixed value, leave the prompt blank.
Prompt Description – Not enterable, the prompt description is derived from prompt number.
Data Type – The data type, one of:
o ‘DATE’ to use a date expression – this can be a fixed date value or a SQL generated date like “SYSDATE”
Page 20 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
o ‘DERV’ to use SQL to derive a value, for example via a DECODE statement. This statement is a maximum of 500 characters long.
o ‘FIXED’ to hardcode a static value
o ‘REF’ to use an application query to derive a value –similar to a DERV expression but supports longer statements, up to 4096 characters, and is based on an application query entry.
Derived Value – When data type is DERV or DATE, SQL is used to create an expression which evaluates to a value. For example, if data needs to be forced to uppercase in the incoming data, you could use UPPER(its_interface_data1)
Fixed Value – Contains the fixed value to be inserted into the map column.
Date Format – This details the formatting to be used for the date value, e.g. “RRRRMMDDHH24MISS”
Notes – Enter any additional description for the mapping, this is for narrative use only.
Notes on derivations and expressions
A DERV expression must be a valid SQL statement, which can include SELECT expressions. Any SQL internal function, e.g., DECODE (), NVL (), SUBSTR () etc can be used, or a more complex expression using SELECT… statements can be built. When using a SELECT statement, the full statement MUST be enclosed with ( and ) or the system will generate a parsing error.
So, for example, if the current system date is required in the data a DERV expression such as (SELECT sysdate FROM dual)could be set up. If it was a DECODE, then using DECODE(its_interface_data1, ‘CODE’, ‘Y’, ‘N’) is a valid expression.
Interface columns (i.e., the column associated with a particular prompt) are referenced using its_interface_data1, its_interface_data2 etc, where the trailing digit is the prompt number, between 1 and 255.
Specifying the prompt will prevent any DERV expression from functioning.
There is a special mapping column in every dataset called IGNORE_SET. If the value in the prompt or the derived expression for this mapping evaluates to a Y then that process will be ignored, i.e., none of the mappings for that set will be processed.
If it evaluates to N then the row of data will be processed.
REF expressions are exactly like DERV expressions, except the expression is defined in the application queries screen as this supports longer expressions. The same rules as for a DERV expression apply. DERV has a maximum of 500 characters, REF, a maximum of 4096.
Page 21 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
REF queries support anonymous PL/SQL blocks (to raise specific errors for example), DERV expressions do not.
Any value which is passed as a NULL in the mapping tells the interface process not to change the data already in the system. You cannot, therefore, update a field to a null value by using NULL as the derived expression. In an update process, for example, if your DERV expression evaluates to NULL, then the data in NetOne will not be changed for that column.
An example
In this example we can see several processes defined. The first two of these are for the works orders screen. Process 10 is an insert, and process 20 is an update. Process 30 is for the dynamic record associated with the works order which was created in step 10 or updated in step 20.
Process 10 is an insert instruction for the works order screen – this is the first process to run as it has the lowest process number.
The very first mapping (line 10) is the IGNORE_SET and determines if this process fires at all. It is a DERV expression, which results in a Y or N outcome, when it is Y the process does not run at all and the insert does not happen, i.e., IGNORE = YES.
If we look at the DERV expression we see this:
DECODE(its_interface_data1, '0', 'Y', '2', 'Y', '3', 'Y', '5', 'Y', DECODE((SELECT 1 FROM DUAL WHERE EXISTS (SELECT 1 FROM works_orders WHERE SUBSTR(wor_udk, 3,4) = SUBSTR(its_interface_data2,3,4))), 1, 'Y', 'N'))
The first DECODE looks at the value in the first column of data, prompt 1, and if this contains 0, 2, 3 or 5 it immediately returns a Y, thus ignoring the process. For values 2 or 4 a further expression is evaluated, this is another DECODE with an embedded SELECT statement. This SELECT expression returns a value of 1 when the data in prompt 2 contains a works order UDK which already exists in the database (actually not quite the full UDK, it’s the last 4 characters). The decode then returns a Y or an N based on the UDK existing in the database.In words, this IGNORE_SET will only allow the data to be processed if the value in column 1 is a ‘2’ or a ‘4’ AND if the works order defined by the value in column 2 does not already exist – because this is an INS process.
Page 22 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Mapping 20 is a more simple DERV expression,:REPLACE(its_interface_data2, 'NOM', '')
which simply removes any occurrence of the string “NOM” from the data.
Mapping 30 is a DERV expression which makes a call to an internal NetOne function, which validates the column 3 value against the lookup domain REG.
Process 20 is the next process, it is for the same data as in process 10 however, this time it is an UPD action.
This time the IGNORE_SET is slightly different:
DECODE(its_interface_data1, '0', 'Y', '2', 'Y', '3', 'Y', '5', 'Y', DECODE((SELECT 1 FROM DUAL WHERE EXISTS (SELECT 1 FROM works_orders WHERE SUBSTR(wor_udk, 3,4) = SUBSTR(REPLACE(its_interface_data2,'NOM',''),3,4))), 1, 'N', 'Y'))
In words, this IGNORE_SET will only allow the data to be processed if the value in column 1 is a ‘2’ or a ‘4’ AND if the works order defined by the value in column 2 already exists – because this is an UPD process.
Only fields which can be updated in the works order screen are included in this set of mappings other than the UDK column, as this is mandatory for identifying the works order row.
Process 30 has an important example in it, where the interface cannot use a UDK to identify a row of data (easy when it is a site or a works order row), the internal ID for the data has to be used.
Page 23 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Mapping line 5 looks up the ID value for the dynamic module, using the works order UDK (because the ID for the dynamic is generated by the system against the works order)
(SELECT wor_dre_id FROM works_orders WHERE SUBSTR(wor_udk,3,4) = SUBSTR(its_interface_data2,3,4) AND wor_udk NOT LIKE '%TXN')
6.1.4. Default Values Tab
The Default Values Tab allows the configuration of default values for prompts in the Interface Data Screen.
Default values are used to define a value which will be placed into a prompt, (the target prompt), when the value in the source prompt is provided. An expression can be used to create some logic which applies different prompt values under different circumstances. For example, serialised part processing, if a prompt exists for serial number and quantity, a default value could be used to set the quantity to 1, when a serial number was provided in the serial number prompt.
Figure 3 - Default Values tab
Page 24 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Source Prompt – This is the sequence number of the trigger prompt which causes the default value to be calculated. When the cursor focus moves out of this prompt the default value will be calculated and the value placed in the target prompt.
Enter the sequence number for the source prompt or use the LOV to populate the details.
Source Description – The description for Source Prompt, a display only field which displays the source prompt description.
Target Prompt – This the sequence number of the target prompt which receives the calculated default value.
Enter the sequence number of the prompt that will be populated with the default value or use the LOV to populate the details.
Target Description – The description for target Prompt, a display only field which displays the target prompt description.
SQL Statement – This is the application query statement which calculates the default value.
Enter the UDK of the SQL statement to be used to populate the Target Prompt or use the LOV to select the appropriate SQL statement. Only application queries defined as type LOV can be used here.
The SQL query will be displayed in the non-updateable SQL field at the bottom of the screen.
Page 25 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.1.5. Users Tab
The User Tab defines which users are allowed access to the transaction. Only users which are on this list will be able to use the interface in the interface data screen, or be able to run the interface as part of a file upload.
Figure 4 - Users tab
User – Enter the NetOne user allowed access to the interface transaction. Alternatively use the LOV to populate the user and name.
Name – The name of user. This is derived from the user details.
Page 26 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.1.6. Extra Validations Tab
The Extra Validations Tabs allows the configuration of more complex validation procedures for the transaction type record. The tab is designed for use by more experienced NetOne administrators.
Figure 5 - Extra Validations tab
1. Line No. – Enter line number of validation record e.g. 1, 2, 3, 4, 5 etc. This will determine the order the record is displayed in the block.
2. Process Sequence – Enter unique process sequence number. Use LOV to populate Process Sequence and Description. This is the data set process number, which is associated with this validation.
3. Description – Description derived from process sequence number.
4. PL/SQL Code – Enter PL/SQL Code to be used for this validation. Use LOV to populate PL/SQL Code and PL/SQL Description.
5. PL/SQL Code Description – Description for PL/SQL Code, derived from the PL/SQL Code.
6. Before/After Flag – This will determine when the validation will be processed i.e. before or after the action (e.g. insert, update, delete).
Page 27 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.2. File Upload Configuration Screen
The file upload configuration defines the contents and layout of a data file which is to be loaded into the system. This may be a manual load initiated by the user, or one which is included in a scheduled, automated load.
6.2.1. File Details Tab
The File Details tab allows the interface file to be defined and mapped into the system. The definition of the interface file is called the file type.
Figure 6 - File Details tab
File Type – A unique identifier for the file type. The file type identifies the interface file to be uploaded.
Description – A short description for the file type.
File Format – This is the data format of the interface file data. Valid values are:
o ‘ASCII’ represents a delimited ASCII file
o ‘DCS’ represents a DCS output file
o ‘XML’ represents an XML document
Transaction Type – This is the interface transaction which the file upload is based on (as defined by the prompt values etc). Enter a transaction type or use the LOV to populate the details.
Transaction Description – Derived from Transaction Type, this is not a user enterable field.
Interface Table – This is the table where the interface data is to be loaded. In nearly all cases this will be the INTERFACE_TRANSACTIONS table – which is also the default for this field.
Table Alias – Derived from the Interface Table, this is not a user enterable field.
Page 28 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Delimiter – Enter field delimiter used within the interface file. This can be any ASCII printable character. Generally, a comma separated value file uses a comma “,” as the delimiter.
Error Handle – Select the method used to handle errors i.e. detected during data uploading into interface table:
o ‘Stop when error’ - The upload process stops after detecting an error and none of the rows in the data file will be submitted to the interface.
o ‘Process when error’ – The upload process reports any error which is detected, but will submit any rows which are correctly processed.
Remove – When this checkbox is checked the physical interface file will be removed from the system after processing.
File Name – The physical name of the interface file.
Directory Path – File server directory path of the interface file.
6.2.2. Column Mapping Tab
The Column Mapping tab displays the prompt mapping onto the generic interface table. In general this tab does not need to be configured because this will be automatically populated using the columns from the transaction type record and the columns from the table INTERFACE_TRANSACTIONS.
Figure 7 - Column Mapping tab
Del Sequence – Enter field sequence number.
Column Name – Enter the column name which comes from the interface table column names. This is the name of the interface table column where the data will be stored from the upload. Use the LOV to populate the Column Name.
Page 29 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Column Description – Interface table column description derived column name.
Date Format – A date format can be applied to the data if desired using one of the list of formats from the LOV.
6.2.3. Users Tab
The Users tab provides the facility to identify users who can use this file type for uploading. When a user has NOT been given access to this file type, the file type will not be displayed in this screen.
Figure 8 - Users tab
User Login – Enter the user to provide that user with access to this file upload type. Alternatively use the LOV to populate User Login and User Name.
User Name – Derived from user login, is not a user enterable field.
Page 30 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.3. File Upload Screen
The File Upload screen provides the facility to upload files into NetOne, based on the configuration defined in the File Upload Configuration Screen.
This screen is used to manage the process, and shows the status of the files previously submitted, along with any errors associated with that file. It is also used to re-submit a corrected file if that file has failed to load.
6.3.1. File Type Tab
The File Type tab is query only and non-updateable – it shows all the interface file configurations to which the current user has access.
Figure 9 - File Type tab
Page 31 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.3.2. Upload Files Tab
The Upload Files tab shows the detailed history of any files uploaded for the selected file type.
Using the control buttons on the screen files can be uploaded or re-loaded into the interface for processing on a manual basis. This is useful for one-off processes or data-migration.
The bottom block of the screen shows any errors produced by the interface file.
Figure 10 - Upload Files tab
Upload Button – Select an interface file to upload into interface tables. When selected a popup window will appear to allow the selection of an interface file on the client. Once an interface file has been successfully selected a new upload file record will be displayed in the block. To process the upload record, use the Interface Manager Screen to start the upload manager job. To check that the file upload was successful, access the Interface Records Screen to check the status of the file upload.
Reload Button – Select to reload the interface file into the generic interface table.
Page 32 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.4. Interface Data Screen
The Interface Data Screen provides the facility to view the interface transaction configured in the Interface Transaction Screen. On first entry to the Interface Data Screen the screen is automatically queried and interface transaction types with the appropriate attached user access privileges are displayed here.
6.4.1. Types Tab
The Types tab displays interface transactions and their corresponding prompts.
Figure 11 - Types tab
On entry to the tab, all transactions belonging to the user are displayed. This tab is query only and not updateable.
Page 33 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.4.2. Data Entry
The Data Entry tab displays all the prompts that are configured for an interface transaction type. The interface transaction type predefines the display order of the prompts. This was configured in the Interface Transaction screen.
Figure 12 - Data Entry tab
To test that an interface transaction type has been configured correctly the Data Entry tab may be used to manually enter a transaction data record into the generic interface table i.e. INTERFACE_TRANSACTIONS. To add data, enter data into the prompts displayed and select save. Use the vertical scroll bar to view prompts hidden at the bottom of the screen. The Interface Manager screen will be used to start a job to load the data into the interface tables.
6.5. Interface Records Screen
The Interface Records screen provides the facility to view transaction data. It is useful for checking the status of transaction data after processing by the job manager: -
Interface File Upload – Data loading from interface file to generic interface table.
Data Mapping – Data Loading from generic interface table to interface tables.
Data Processing – Data Loading from interface files to NetOne tables.
Page 34 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.5.1. Transaction Data Tab
The Transaction Data tab is query only and not updateable. On first entry to the Transaction Data tab the tab is automatically queried.
Figure 13 - Transaction Data Type
ID – Unique identifier for the transaction data record.
Transaction Type – The transaction type that derived the transaction data record.
Status - Each Transaction Data record has a status. Using the Interface Manager Screen, transaction data records with a status of NEW may be processed. For further details refer to the section regarding the Interface Manager screen. The statuses represented are: -
o ‘NEW’ – The interface manager has not processed this transaction data record.
o ‘PROC’ – The interface manager has successfully processed this transaction data record.
o ‘R’ – This transaction data record has been resubmitted to the interface manager after fixing the transaction data using the Error Correction screen.
o ‘ERR’ – This transaction data record has been unsuccessfully processed.
Hold – When checked this will indicate that the transaction data record has been processed successfully, however related transaction data records may have errors. This will be unchecked once the related transaction data record has been resubmitted for processing by the interface manager.
Page 35 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Attempts – This displays the number of time the transaction data has been unsuccessfully processed by the interface manager.
Version – This will be set to 1 and incremented by 1 every time the transaction data is fixed using the Error Correction screen. The version number refers only to the raw data in the generic interface table e.g. INTERFACE_TRANSACTIONS.
Manager – The interface manager in the Interface Manager screen that may processes this transaction data record.
Table Name – The table name where the transaction data record is currently residing.
Table Alias – The description for the table name.
Queue – The interface manager that will process this transaction data record.
Set No. – The processing sequence number defined in the Interface Transactions Screen.
Original ID – The identifier of the generic interface table i.e. INTERFACE_TRANSACTIONS.
Ext Source Name – Name of the external application that created the transaction data record.
Ext Source Code – Unique identifier of external application.
Parameter 1 to 7 and Date Parameter 1 to 3 – These will be used to display values that are passed as parameters for processing the transaction data record.
Page 36 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.5.2. Errors Tab
The Errors tab is query only and non-updateable. The tab displays errors created for each transaction data record.
Figure 14 - Errors tab
Error Code – Unique number to identify the error.
Error Source – The source or origins of the error i.e. package procedure that created the error.
Error Message – The description of the error. This will be used to identify and fix the error using the Error Correction Screen.
Error Date – The date and time, when the error was created.
Page 37 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.5.3. Interface Data Tab
The Interface Data tab is query only and non-updateable. The tab displays the interface data associated with the transaction data ID.
Figure 15 - Interface Data tab
This tab will only display transaction data records with a table name of ‘INTERFACE_TRANSACTIONS’. The number of prompts displayed will be determined by the configuration in the Interface Transaction screen.
6.6. Error Correction Screen
The Error Correction screen provides the facility to correct data that has been unsuccessfully processed e.g. mapping from generic interface table to interface table or loading from interface table to NetOne tables.
Page 38 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.6.1. Error Record Tab
The Error Record tab displays all transaction data record with an error status in the generic interface table i.e. INTERFACE_TRANSACTIONS. The Corrected check box is the only updateable field on the Error Record Tab. The other fields on the Error Record Tab are query only and non-updateable.
Figure 16 - Error Record tab
ID – Displays unique sequence number for identifying the transaction data record in the API Inbound Interface.
Corrected – Update the transaction data record, correcting the error and the check box will be checked. When checked the transaction data may be processed by the appropriate error correction manager interface manager from the Interface Manager Screen.
Transaction type – Displays the related transaction type for the transaction data record.
Scan Date – Displays the date and time when the transaction data record was scanned in. This will be the date and time when the transaction data record was extracted from the scanner or external application/device.
Transaction Upload Date – Displays the date and time when the transaction data record was uploaded into the generic interface table i.e. INTERFACE_TRANSACTIONS.
External Source Name – Displays the external application that created the transaction data record in the generic interface table.
External Source Code – Displays the code that was used to extract or identify the transaction data record in the external application.
Data 1 to Data 75 – Displays the transaction data prompts from 1 to 75. These prompts or columns may be updated to fix an error.
Page 39 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.6.2. Interface Data Tab
The Interface Data tab displays the same transaction data prompts as the Interface Data Record screen, but in a user-friendlier layout. The Interface Data tab displays the transaction data record as configured in the Interface Transaction Screen. The Interface Data tab is query and updateable. The tab provides the facility to query and correct erroneous transaction data.
Figure 17 - Interface Data tab
Errors – Select the Errors button to display all the errors related with the transaction data.
Corrected – Update the transaction data record, correcting the error and the check box will be checked. When checked the transaction data may be processed by the appropriate error correction manager interface manager from the Interface Manager Screen.
Once the data has been corrected select save to commit the data.
Page 40 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.7. Interface Tables Screen
6.7.1. Interface Tables Tab
The Interface Tables Screen displays a list of interface tables that are available in the Gamma NetOne API Interface.
Figure 18 - Interface Tables tab
Table Name – This displays the interface table name. This column is query only.
User Defined Table Alias – This displays the interface table description. This column is updateable.
Column Name – This displays the interface column name. This column is query only.
User Defined Column Alias – This displays the column description. This column is updateable.
Page 41 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.8. Archive Screen
The archive function may be switched on when creating an interface transaction using the Interface Transaction screen. The Archive screen provides the facility to query all archived transaction data. The Archive screen is query only.
6.8.1. List View Tab
The List View tab displays all archive interface transaction type data in a tabular format. This tab is query only.
Figure 19 - List View tab
Transaction ID – Display unique identifier for transaction data record.
Version No – Display the version of the transaction data record. The version number is incremented every time the transaction data record is processed by the error correction process.
Transaction Type – For further details refer to Error Correction screen.
Scan Date – For further details refer to Error Correction screen.
Date Upload – For further details refer to Error Correction screen.
Date Processed – Displays the date the transaction data record when the data map manager inserted the record into archive.
Source System – For further details refer to Error Correction screen.
Source Code – For further details refer to Error Correction screen.
Page 42 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Status – Displays the status of the transaction data record.
Error Indicator – Displays the ‘ERR’ for an error.
Username – Displays name of user who created this transaction data record.
Date/Timestamp – Displays the date and time when this transaction data record was created.
Data 1 to Data 75 – Displays the prompt data.
6.8.2. Record View Tab
The Record View tab displays archived transaction data records in more user-friendly form layout. This tab is query only.
Figure 20 - Record View tab
6.8.3. Error Message Tab
The Error Message tab displays any errors related to the interface transaction type. This tab is query only.
Figure 21 - Error Message tab
Page 43 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
6.9. Application Queries Screen
The Application Queries screen provides the facility to view and create SQL queries. These SQL queries will be made available to the API Inbound Interface i.e. attach the SQL queries to different prompts.
6.9.1. Query Tab
Figure 22 - Query tab
Code – Enter a unique name for the SQL query.
Description – Enter a description for the SQL query.
ASCII SQL – When checked indicates an ASCII SQL.
LOV SQL – When checked indicates a LOV SQL.
DESC SQL – When checked indicates description LOV SQL.
PL/SQL – When checked indicates procedural language SQL.
SQL Statement – Enter SQL command. An understanding of SQL programming is essential here.
Test SQL – Select button to test the SQL command syntax. The following additional tests take place depending on the SQL query type: -
o ASCII SQL – Only one column may exist in the SELECT part of the SQL statement, e.g.
Page 44 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
‘SELECT sit_udk, sit_name FROM SITES’
is invalid because it contains two columns in the SELECT part.
o Description SQL – Only one column may exist in the SELECT part of the SQL statement. An additional :CODE should appear in the WHERE part of the SQL statement, e.g.
‘SELECT sit_name FROM sites WHERE sit_udk = :CODE’.
:CODE will be replaced with the value in the prompt at runtime and the corresponding description will be displayed next to the prompt on the Interface Data screen.
LOV SQL – The maximum number of columns allowed in the SELECT part of the SQL statement is three. The :n may be used in the WHERE part of the SQL statement to identify prompts 1 to 75.
PL/SQL – Reserved keywords are not allowed e.g. COMMIT and ROLLBACK. The word :ROWID should appear in the PL/SQL block. The :ROWID will allow all column values associated with the :ROWID to be captured and processed with extra validation.
6.10. Other Screens
NetOne provides a generic audit functionality, to allow the audit of NetOne oracle tables. This functionality may be used to audit the API Interface tables and related NetOne tables. Two screens exist to provide this functionality called: -
Audit Definition Screen – The configuration of the oracle table audit functionality.
Audit Log Screen – Displays all oracle table audit logs configured in the Audit Definition screen.
Page 45 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
7. Automating the API Inbound Interface
It is possible to load files from a fixed directory, accessible to the database (either locally or remotely), into the NetOne application, scheduled as an automated job. Before this interface can be created, the inbound API must have already been set up (see section 3 for details). In addition, the location of the files must have been set up in the File Locations screen. Users may wish to specify file naming rules that inbound files must satisfy in order to be loaded by the automated interface. If so, these must have been pre-defined in the File Naming screen.
See section 5 for details of how to manage the jobs associated with the automated interfaces, including how to view the history of jobs that have already been run and how to schedule new jobs immediately.
7.1. File Locations Screen
This screen allows users to define the paths where the inbound files will be picked up by the automated interface. Files can be picked up both locally from the database server and from remote hosts.
7.1.1. Local Directories Tab
This tab enables users to define directories on the database server where the inbound files will reside. Note that the operating system user running Oracle on the database server must have read / write / delete privileges on the local directories set up in this tab. If the operating system is Windows, this user is generally administrator; for UNIX it is usually the Oracle user.
The NetOne application owner needs to be granted the Java ‘read’ permission on the local directories that the automated interface is to load files from. It is suggested that this permission is granted on ALL local directories by connecting to the database as the SYSTEM or SYS user and running the following command:
EXECUTE dbms_java.grant_permission( 'NOD_KPN', 'SYS:java.io.FilePermission', '<<ALL FILES>>', 'read');
Alternatively, it is possible to grant the Java ‘read’ permission on individual directories. To do so, connect to the database as the SYSTEM or SYS user and run a command similar to that given below for EACH local directory that a file is to be read from:
EXECUTE dbms_java.grant_permission( 'NOD_KPN', 'SYS:java.io.FilePermission', '/u02/kpnapi/PRIME’, 'read');
Page 46 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Figure 23 - Local Directories tab
Local Directory UDK – Enter a unique identifier for the local directory.
Local Directory Description – Enter a description for the local directory.
Local Directory Path – Enter the path of the directory where the files are to be held. Note that this must be a valid directory on the database server, without a trailing slash.
UTL_FILE Directories – This non-updateable field displays the database initialisation parameter UTL_FILE_DIR that specifies which directories on the host the database can read from / write to.
SYSTEM Password – Enter the password of the database SYSTEM user, which is needed to validate that the local directory path is valid.
If the local directory is valid and the Oracle user has the appropriate permissions on it, the message ‘Permissions successfully set’ will be displayed on saving the record.
7.1.2. Remote Directories Tab
This tab allows users to define the hosts and file paths of remote systems that will be used to hold inbound files.
On the remote FTP server, create or identify an existing operating system username and password. Create a new directory owned by this user on the remote host and grant write permission on this directory to the operating system user running Oracle on the database server. If the operating system is Windows, this user is generally administrator; for UNIX it is usually the Oracle user.
Page 47 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
A number of Java permissions need to be set up before the record can be created in the Remote Directories tab of the File Locations screen. These should be established by connecting to SQL * Plus as the SYSTEM or SYS user on the database the automated interface is to be created on and running the following commands:
execute dbms_java.grant_permission('<application_owner>', 'SYS:java.net.SocketPermission', '<remote_host_name>', 'resolve');
execute dbms_java.grant_permission('<application_owner>', 'SYS:java.net.SocketPermission', '<remote_host_ip_address>:<remote_host_ftp_port ', 'connect,resolve');
execute dbms_java.grant_permission('<application_owner>', 'SYS:java.net.SocketPermission', '*:*', 'accept,listen,connect,resolve');
Once these Java permissions have been set, log out of NetOne and back in again before creating records in the Remote Locations tab to ensure that they are picked up. The existence of these java permissions can be checked on the database by looking in the DBA_JAVA_POLICY view where the GRANTEE = <application_owner>. If the permissions are not present, the record will not save. On saving the record, a test connection is established with the directory on the remote server. Only if this is possible is the record saved. Note that once a record has been created, only the remote directory description field is updateable.
Figure 24 - Remote Directories tab
Remote Directory UDK – Enter a unique identifier for the remote directory.
Page 48 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Remote Directory Description – Enter a description for the remote directory.
Remote Server Name – Enter the name or ip address of the remote server where the files are to be held.
Username – Enter the username of the user that is to connect to the remote server in order to FTP the files back to the database server.
Password – Enter the password of the user that is to connect to the remote server via FTP.
Remote Server Directory Path – Enter the path on the remote server where the files are to be held. Note that this must be a valid directory on the remote server, without a trailing slash.
7.2. File Naming Conventions Screen
This screen is used to set out any file naming rules that inbound files must satisfy in order to be loaded by the automated interface. Specifying such rules is optional when configuring an inbound automated interface.
Note that if a file naming convention is in use by an automated interface, it may not be deleted, and only its description may be updated. Details cannot be removed, added to or updated against such a record.
Figure 25 -File Naming Conventions screen
Convention UDK – Enter a unique identifier for the file naming convention being defined.
Description – Enter a description for the file naming convention.
Page 49 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Sequence – Use this to specify the order with which the component parts that make up the filename will appear.
Type – Select the type of string that makes up this component part of the filename. Choose from Fixed Value, Sequence Number or Timestamp. If Fixed Value is chosen, the Fixed Value field is to be entered; if Sequence Number is chosen, the Digits field is to be entered; if Timestamp is chosen, the Date Format String field is to be entered. Note that the types of Fixed Value and Sequence Number can only be entered once for a given file naming convention. Also note that the Oracle wildcard ‘*’ symbol can be used in the Fixed Value field to introduce greater flexibility into the file naming convention being defined.
Rename Option – This is used to specify how this part of the filename is to be changed if the inbound interface has been set up to rename the file (in the File Option field of the Locations tab, Automated Interfaces screen). The following options are available – Append, Change, Delete, Leave and Prepend. For the Append, Change and Prepend options, the change string must be included in the Rename Value field.
7.3. Automated Interfaces Screen
The Automated Interfaces screen provides the ability to load files from a fixed directory accessible to the Oracle database into the NetOne application, scheduled as an automated job. The mappings associated with loading the flat file into the application must have been pre-defined in the Interface Transactions and File Upload Configurations screens and the location of the files must have been set up in the File Locations screen.
7.3.1. Definition Tab
As part of the automated interface the Definition tab allows the automated interface to be named and defined at a general level.
Figure 26 - Definition tab
Page 50 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Interface UDK – Enter a unique identifier for the automated interface.
Interface Description – Enter a description for the automated interface.
Direction – Select ‘Inbound’ from the LOV to create an inbound interface.
Interface Type – Select the Interface Type from the LOV as defined in the Upload File Configuration screen.
Active – Whether or not the interface is active. Only set the interface to active once it has been fully defined in the Automated Interfaces screen.
Disabled – Whether or not the interface is temporarily disabled
File Type – Disabled for inbound interfaces
Delimiter – Disabled for inbound interfaces.
Recurring – When checked, the interface is recurring; unchecked is scheduled to run once only.
Max Recurrences – Enter the maximum number of times the interface can run. If this is left NULL, it is assumed that there is no upper limit.
Start Date – Enter the earliest date the interface can run. This is mandatory.
End Date – Enter the latest date the interface can run.
Last Date – The last date the interface ran – non-updateable.
Next Date – The next date the interface will run – non-updateable.
Sequence Number – If inbound files are based on a sequence, the last value used.
Run Count – Number of times the interface has run – non-updateable.
Fail Count – Number of times the interface has failed – non-updateable.
Page 51 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
7.3.2. Scheduling Tab
The Scheduling tab enables users to set up the frequency with which the interface will run. This tab will only be enabled if the interface is marked as ‘Recurring’ in the Definitions tab.
Figure 27 - Scheduling tab
Scheduling Mode – if the checkbox is checked, the interface uses fixed time scheduling, if the checkbox is unchecked the interface uses interval scheduling.
Fixed Time Scheduling
Sequence – Sequence number of the scheduling option currently being configured.
Timescale – Select the appropriate radio button to define the frequency with which the interface will run, i.e. daily, weekly, monthly or yearly. Once selected, this then results in further options being displayed for the times that the interface is to be run that need to be defined by the user – see Time below.
Time – Select the appropriate checkboxes / radio group and complete the relevant fields to define at which fixed point(s) in time the interface is to be run.
Interval Scheduling
Interval – Enter the time interval with which the interface is to be run Timescale – Enter the timescale the interval is to operate over, i.e. seconds, minutes, hours,
days or weeks
Page 52 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
7.3.3. Locations Tab
The Locations tab allows the location of the files to be processed by the interface to be defined. These files can be held either locally on the database server or on a remote host. It also allows the user to determine what should happen to the file once it has been loaded.
Figure 28 - Locations tab
Local Directory UDK – Select the local directory where the files are to be picked up from, as defined in the Local Directories tab of the File Locations screen.
Local Directory Path – Path on the database server where the files are to be held locally, as defined in the File Locations tab and automatically completed when the Local Directory UDK is selected.
Remote Directory UDK – Select the remote directory where the files are to be picked up from, as defined in the Remote Directories tab of the File Locations screen.
Remote Directory Path – Path on the remote server where the files are to be held, as defined in the File Locations screen and automatically completed when the Remote Directory UDK is selected.
Remote Server – Name of the remote server where the files are held, as defined in the File Locations screen and automatically completed when the Remote Directory UDK is selected.
Delete Source – Only enabled when a remote directory is in use – checked means that the files are deleted from the remote host after FTP transfer; unchecked means they are not deleted.
File Option – Allows the user to perform a specified action on the files after the dataload. The options available are ‘delete’, ‘leave’, ‘move’, ‘rename’, ‘move and rename’.
Page 53 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Move Directory UDK – Enter the local directory on the database server where the files are to be moved to after processing. This option is only applicable when the File Option is set to ‘move’ or ‘move and rename’. Note that the Move Directory UDK is defined in the Local Directories tab of the File Locations screen.
Move Directory Path – Path on the database server where the files are to be moved after processing as defined in the File Locations screen and automatically completed when the Move Directory UDK is selected.
7.3.4. Inbound Filters Tab
The Inbound Filters tab enables the user to filter inbound files to be processed by the automated interface according to file name, file size or last modified date.
Figure 29 -Inbound Filters tab
Filter On Name – When checked, the inbound files are filtered by name, when unchecked they are not filtered in this way. Checking the box automatically enables the File Naming tab where the rules governing the name filtering can be defined.
Filter On Size – When checked, the inbound files are filtered by size, when unchecked they are not filtered in this way. Checking the box means that the minimum and maximum file sizes (in bytes) must be defined.
Filter On Date – When checked, the inbound files are filtered on date modified, when unchecked they are not filtered in this way. Checking the box enables the radio group that defines how the files are filtered by date modified, the options being Modified Since, Modified In The Last and Modified Since Last Interface Run. In the case of the first two options, the appropriate date or time period must be completed.
Page 54 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Allow Reload – When checked, an inbound file with the same name as has already been used can be reloaded.
Reload Using Size – When checked, an inbound file with the same name as has already been used can only be reloaded if it differs in size to that which has already been loaded.
7.3.5. File Naming Tab
This tab allows users to define one or more file naming conventions that the inbound files must satisfy before being automatically loaded into NetOne.
Figure 30 - File Naming tab
Sequence – Use this to determine the order with which the file naming convention rules are applied to the inbound files.
File Naming UDK – Select the file naming convention from the LOV that is to be applied to the files, as defined in the File Naming Conventions screen.
File Naming Description – Description of the file naming convention which is automatically completed when the File Naming UDK is selected.
Page 55 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
8. Managing the Automated Interfaces
This section explains how the database jobs that are used by both the inbound and outbound API’s can be managed. It explains how the history of the database jobs that have already been run can be viewed. In addition, the process by which the next scheduled run date of the interface can be calculated and how the interface can be rerun immediately is explained.
8.1. Interface History Screen
This popup screen is called by right-clicking on the appropriate interface in the Automated Interfaces screen in the Definitions tab and selecting ‘Options’ > ‘Interface History’.
8.1.1. Interface Runs Tab
This tab displays the history of all the run dates for this interface. As such, it is non-updateable.
Figure 31 - Interface Runs tab
Run Start Date – Time and date the interface started running.
Run End Date – Time and date the interface completed.
Run Result – The highest level of message that was encountered during the interface run. This will be one of ‘E’ – error, ‘W’ – warning or ‘I’ – information. ‘E’ runs are displayed in red, ‘W’ in yellow and ‘I’ in green.
Run Status – ‘Completed’ if the run has completed, else this will be ‘Executing’.
Page 56 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
8.1.2. Interface Run Data Tab
This tab displays the details of all the files uploaded / downloaded during the interface run selected in the first tab. As such, it is non-updateable.
Figure 32 - Interface Run Data tab
Filename – Name of the file uploaded / downloaded.
Local Directory – Path on the database server where the file was uploaded from / downloaded to.
File Size – Size of the file in bytes.
8.1.3. Interface Run Messages Tab
This tab displays all the messages that were encountered during the interface run selected in the first tab. As such, it is non-updateable.
Figure 33 - Interface Run Messages tab
Log Date – Date and time the message was recorded.
Page 57 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Type – The type of message. This will be one of ‘E’ – error, ‘W’ – warning or ‘I’ – information. ‘E’ messages are displayed in red, ‘W’ in yellow and ‘I’ in green.
Message Text – Text associated with the message recorded.
8.2. Calculating the Next Run Date
A right-click menu option is available in the Definition tab on the ‘Automated Interfaces’ screen, to allow the next run date of an interface to be recalculated. This will be required if the scheduling parameters of a job are modified while an interface is active.
8.3. Scheduling an Interface Run Immediately
A right-click menu option is available in the Definition tab on the ‘Automated Interfaces’ screen, to allow the next run date of an interface to be set to the current date, so that the interface is run immediately.
Page 58 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
9. Overview of API Outbound Interface
This section is intended as a user guide for the NetOne API Outbound Interface, and includes information about how to configure the API Outbound Interface. This document is based on the Product Extension Requirement document called ‘Gamma_GBL_PER0009_1.00’.
Figure 34 - API Outbound Interface Data Flow
The API Outbound Interface provides a mechanism for the NetOne application to interface with other external applications. A combination of user instructions and examples will be provided in the document to explain the API Outbound Interface functionality.
This section is intended for NetOne Administrators with knowledge in the use of the Oracle SQL programming language.
Page 59 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10. Screens of API Outbound Interface
The API Outbound Interface Module includes the following screens: -
File Download Configuration screen.
Download File screen.
User Requests screen.
During the API Outbound Interface configuration all mandatory screen fields must be entered. If a mandatory field is NOT entered then an appropriate warning message will be displayed. If unsure of the mandatory fields select save and the NetOne Application will display a warning message identifying the mandatory fields.
The order in which the screens have been listed above is NOT necessarily the correct sequence of events in order to configure the API Outbound Interface. This order of events may vary.
10.1. Interface Generation
The following diagram illustrates a suggested method of configuring the API Interface for generating an interface file. This is only a suggested sequence of events and may vary.
Page 60 of 78 Confidential, Enghouse Networks Ltd
File Download Configuration Screen
Download File Screen
User Requests Screen
Start
Stop
Application Queries
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.2. Application Queries Screen
The Application Queries screen is used to create an SQL query. The SQL query will be used to extract the NetOne data to create the interface file. Refer to the API Inbound Interface, Applications Queries screen for instructions on how to create a SQL query.
Figure 35 - Application Queries Screen
However to make the SQL query available when configuring the API Outbound Interface Outbound checkbox must be checked. Use the button ‘Test SQL’ to ensure that the SQL query is syntactically correct.
Page 61 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.3. File Download Configuration Screen
This screen allows the configuration of outbound transactions. This is accessed by clicking on the File Download Conf. button within the APIs tab of the NetOne Administration menu.
10.3.1. Outbound Transaction Tab
The Outbound Tab allows the query, creation and update of outbound transactions.
Figure 36 - Outbound Transaction tab
Code – Enter a unique outbound transaction code. This is mandatory and should be continuous i.e. no breaks in the unique identifier. This field is non-updateable and query.
Description – Enter a user-friendly description for the transaction code. This field is updateable and query.
Query Code – Enter a SQL query to be used for the data extract from Gamma NetOne. Use the LOV to select a predefined SQL query. The SQL query is predefined in the Application Queries Screen. This field is mandatory, non-updateable and query.
Description – Derived from the Query Code.
Active – When checked will make the outbound transaction available to all users for exporting data from NetOne. When unchecked the outbound transaction will not be available to users. The default value is checked. If unsure use default. This field is optional, updateable and query.
Changed – Will indicate that the SQL Query to be used for exporting data from NetOne has changed.
SQL Statement – Displays the actual SQL statement. Derived from the Query Code.
Page 62 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.3.2. Fields Tab
The Fields tab automatically displays the columns from the SQL query selected in the Outbound Transaction tab.
Figure 37 - Fields tab
Seq No – Enter a unique sequence number, initially derived from the SQL Query in the Outbound Transaction tab. Mandatory, query and updateable.
Field Name – The column name or column alias from the SQL query. The field is query only.
MLS UDK – Enter an existing MLS text to appear as XML tag. Alternatively use LOV to select an existing MLS text. When no MLS text is selected the field name will be used as MLS text. If unsure leave blank. The field is optional, updateable and query.
MLS Label – The description for the MLS UDK. Derived from MLS UDK.
Export? – When checked for a column the column data will be exported. Default value is checked. If unsure use default. The field is updateable and query.
XML Tag – Enter XML tag for DTD. If no XML Tag provided the MLS UDK will be used as the default XML tag.
Refresh – This button will be enabled when the SQL query is changed. Selecting the Refresh button will overwrite the existing Field definitions. Selecting the Refresh button may overwrite the MLS UDK, XML tags etc.
Page 63 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.3.3. Restrictions Tab
The Restrictions tab may be used to apply restrictions on the exported data. This is equivalent of defining the WHERE clause of a SQL SELECT statement.
Figure 38 - Restrictions tab
Columns – Enter a column name. Use the LOV to select a column name based on the SQL Query from the Outbound Transaction Tab.
Operator – Enter an operator. Use the LOV to select an operator.
Value 1 – Enter first value. The operator will determine if this is enabled or not.
Value 2 – Enter second value. The operator will determine if this is enabled or not. Typically this is enabled when a range value operator is used e.g. the operators ‘is between’ or ‘is not between’.
‘(‘ – Select open bracket button to append ‘(‘ to SQL statement.
‘)’ – Select closed bracket button to append ‘)’ to SQL statement.
And – Select AND button to append AND operator to SQL statement.
OR – Select OR button to append OR operator to SQL statement.
Test SQL – Select to Test SQL button syntax of the SQL statement.
Page 64 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Add – Select Add button to display SQL Query configured using the fields Columns, Operator, Value 1 and Value 2.
Statement – Enter extra restrictions directly into the Statement field.
10.3.4. Users Tab
The User tab provides the facility to grant users access to the outbound transaction. When the user is granted access to an outbound transaction the user will be able to view the outbound transaction.
Figure 39 - Users tab
User – Enter a NetOne user. Alternatively use LOV to select a NetOne user.
Name – Derived from user.
Page 65 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.3.5. Preview Tab
The Preview tab will display an example of the export data in the display box.
Figure 40 - Preview tab
No of Records – Enter the number of records to be displayed in the display box. The field indicates the total number of example records that will be displayed in the display box. The default value is held in the system parameter (‘OUT’,’NOREC’).
Format – Enter the format of the displayed example export data.
Preview – Select Preview button to view the example export data in the display box.
Page 66 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.4. Download File Screen
The Download File screen provides the facility to download the NetOne data into an external format e.g. interface file. The NetOne data will be based on the configuration defined in the Outbound Transaction screen.
10.4.1. Export Requests Tab
Figure 41 - Download- Export Files screen
Download – When checked indicates that this interface file has been flagged for generation. This field is updateable.
Request ID – Displays a unique number identifying the user request.
Created On – Displays the date and time when the request was created.
File Name – Displays the filename of the interface file. The interface file is where the download data will be stored. When no filename is entered the interface filename will be determine by the file type e.g. ‘request_id.csv’ or ‘request_id.xml’ will be used as the interface file name. Use this field to change the name of the file name.
Pending – When checked indicates that the request is pending processing by the download function. After the first successful download, the checkbox will be unchecked.
Last Download – Displays the last date and time when the file was downloaded.
Download – Select the Download button to download the files indicated in the Download checkbox.
Page 67 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
10.5. User Requests Screen
The User Requests screen displays queued user requests. This is accessed via the User Requests button on the Materials Management tab of the Administration menu.
10.5.1. User Request Tab
Figure 42 - User Request tab
Submit New Request – Select Submit New Request button to submit a new user request. A popup window will appear.
Request – In the popup window enter a user request type of ‘Outbound Transactions’.
Transaction Type – In the popup window enter the outbound transaction to be submitted for processing.
Output Format – In the popup window enter the format of the output file.
DTD Requested – Enter DTD. Default value is no. If unsure use default value.
Destination Type – In the popup window enter the destination of the export. Use File for data to be exported to interface file.
Once submitted the following events will occur:
The outbound transaction user request will have an initial status of ‘RQD’ representing requested in the User Requests screen.
Ensure that the User Request Manager in the Interface Manager screen is running, if not start the User Request Manager.
Page 68 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
The status of the outbound transaction user request in the User Requests screen will change from ‘RQD’ to ‘RUN’ representing running/processing.
If the user request is successful the status will change to ‘POK’ representing processed OK. Check in the appropriate file directory location for the generated interface file.
If the user request is unsuccessful the status will change to ‘POE’ representing processed with errors. Select the Errors tab to view the reason for the unsuccessful processing.
o Resubmit Request – Select Resubmit Request button to resubmit a previously unsuccessful outbound transaction user request.
o Cancel Request – Select Cancel Request button to cancel an outbound transaction user request.
o View Log – Select View Log to view the processing log for the user request.
10.5.2. Errors Tab
The Errors tab provides the facility to view errors related to an outbound transaction user request.
Figure 43 - Errors tab
Page 69 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
11. Automating the API Outbound Interface
It is possible to automatically generate a file based on a pre-defined Outbound Transaction Configuration (see section 5) and write this file to a fixed directory, either located on the database host or remotely on another server. In order to do so, not only must the outbound interface have been defined, but the location where the files are to be written needs to be specified in the File Locations screen. In addition, the manner by which the newly created file is to be named must already have been established in the File Naming Conventions screen.
See section 5 for details of how to manage the jobs associated with the automated interfaces, including how to view the history of jobs that have already been run and how to schedule new jobs immediately.
11.1. File Locations Screen
This screen allows users to define the paths where the outbound files will be sent by the automated interface. Files can be sent both locally to directories on the database server and remotely to directories on other servers.
11.1.1. Local Directories Tab
This tab enables users to define directories on the database server where the outbound files will be written to. Note that the operating system user running Oracle on the database server must have read / write / delete privileges on the local directories set up in this tab. If the operating system is Windows, this user is generally administrator; for UNIX it is usually the oracle user.
Figure 44 - Local Directories tab
Local Directory UDK – Enter a unique identifier for the local directory.
Local Directory Description – Enter a description for the local directory.
Page 70 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Local Directory Path – Enter the path of the directory where the files are to be written to. Note that this must be a valid directory on the database server, without a trailing slash.
UTL_FILE Directories – This non-updateable field displays the database initialisation parameter UTL_FILE_DIR that specifies which directories on the host the database can read from / write to.
SYSTEM Password – Enter the password of the database SYSTEM user, which is needed to validate that the local directory path is valid.
If the local directory is valid and the Oracle user has the appropriate permissions on it, the message ‘Permissions successfully set’ will be displayed on saving the record.
1.1.1. Remote Directories Tab
This tab allows users to define the hosts and file paths of remote systems where the outbound files will be written to.
On the remote FTP server, create or identify an existing operating system username and password. Create a new directory owned by this user on the remote host and grant write permission on this directory to the operating system user running Oracle on the database server. If the operating system is Windows, this user is generally administrator; for UNIX it is usually the oracle user.
A number of java permissions need to be set up before the record can be created in the Remote Directories tab of the File Locations screen. These should be established by connecting to SQL * Plus as the SYSTEM or SYS user on the database the automated interface is to be created on and running the following commands:
execute dbms_java.grant_permission(‘<application_owner>’, 'SYS:java.net.SocketPermission', '<remote_host_name>', 'resolve');
execute dbms_java.grant_permission(‘<application_owner>’, 'SYS:java.net.SocketPermission', '<remote_host_ip_address>:<remote_host_ftp_port>', 'connect,resolve');
exec dbms_java.grant_permission('<application_owner >', 'SYS:java.net.SocketPermission', '*:*', 'accept,listen,connect,resolve');
Once these java permissions have been set, log out of NetOne and back in again before creating records in the Remote Locations tab to ensure that they are picked up. The existence of these Java permissions can be checked on the database by looking in the DBA_JAVA_POLICY view where the GRANTEE = <application_owner>. If the permissions are not present, the record will not save. On saving the record, a test connection is established with the directory on the remote server. Only if this is possible is the record saved. Note that once a record has been created, only the remote directory description field is updateable.
Page 71 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Figure 45 - Remote Directories tab
Remote Directory UDK – Enter a unique identifier for the remote directory.
Remote Directory Description – Enter a description for the remote directory.
Remote Server Name – Enter the name or ip address of the remote server where the files are to be written to.
Username – Enter the username of the user that is to be used to FTP the files across to the remote server.
Password – Enter the password of the user that is to connect to the remote server via FTP.
Remote Server Directory Path – Enter the path on the remote server where the files are to be written. Note that this must be a valid directory on the remote server, without a trailing slash.
11.2. File Naming Conventions Screen
This screen is used to set out the rules that are to be used in naming the file created by the automated outbound API. It is a mandatory requirement that these rules have been configured prior to the automated outbound interface being set up.
Note that if a file naming convention is in use by an automated interface, it may not be deleted, and only its description may be updated. Details cannot be removed, added to or updated against such a record.
Page 72 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Figure 46 - File Naming Conventions screen
Convention UDK – Enter a unique identifier for the file naming convention being defined.
Description – Enter a description for the file naming convention.
Sequence – Use this to specify the order with which the component parts that make up the filename will be used.
Type – Select the type of string that makes up this component part of the filename. Choose from Fixed Value, Sequence Number or Timestamp. If Fixed Value is chosen, the Fixed Value field is to be entered; if Sequence Number is chosen, the Digits field is to be entered; if Timestamp is chosen, the Date Format String field is to be entered. Note that the types of Fixed Value and Sequence Number can only be entered once for a given file naming convention. Also note that the Oracle wildcard ‘*’ symbol cannot be used in the Fixed Value field for an outbound interface as the filename must be unique.
Rename Option – This should be set to ‘leave’ as the options to ‘rename’ or ‘move and rename’ files (as specified in the File Option field of the Locations tab, Automated Interfaces screen) are not valid for an out bound interface.
11.3. Automated Interfaces Screen
The Automated Interfaces screen provides the ability to generate files based on an existing Outbound Transaction Configuration and write them to a directory either locally on the database server or on a remote server.
Page 73 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
11.3.1. Definition Tab
As part of the automated interface the Definition tab allows the automated interface to be named and defined at a general level.
Figure 47 -Definition tab
Interface UDK – Enter a unique identifier for the automated interface.
Interface Description – Enter a description for the automated interface.
Direction – Select ‘Outbound’ from the LOV to create an outbound interface.
Interface Type – Select the Interface Type from the LOV as defined in the Outbound Transaction Configuration screen.
Active – Whether or not the interface is active. Only set the interface to active once it has been fully defined in the Automated Interfaces screen.
Disabled – Whether or not the interface is temporarily disabled.
File Type – The format of the file that will be generated, mandatory for outbound interfaces.
Delimiter – The delimiter to be used in separating values in outbound ASCII files, therefore only applicable (mandatory) for these file types.
Recurring – When checked, the interface is recurring; unchecked is scheduled to run once only.
Max Recurrences – Enter the maximum number of times the interface can run.
Page 74 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Start Date – Enter the earliest date the interface can run.
End Date – Enter the latest date the interface can run.
Last Date – The last date the interface ran – non-updateable.
Next Date – The next date the interface will run – non-updateable.
Sequence Number – If inbound files are based on a sequence, the last value used.
Run Count – Number of times the interface has run – non-updateable.
Fail Count – Number of times the interface has failed – non-updateable.
1.1.2. Scheduling Tab
The scheduling tab enables users to set up the frequency with which the interface will run. This tab will only be enabled if the interface is marked as ‘Recurring’ in the Definitions tab.
Figure 48 - Scheduling tab
Scheduling Mode – if the checkbox is checked, the interface uses fixed time scheduling; if the checkbox is unchecked the interface uses interval scheduling
Fixed Time Scheduling
Sequence – Sequence number of the scheduling option currently being configured
Timescale – Select the appropriate radio button to define the frequency with which the interface will run, i.e. daily, weekly, monthly or yearly
Page 75 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Time – Select the appropriate checkboxes / radio group and complete the relevant fields to define at which fixed point(s) in time the interface is to be run
Interval Scheduling
Interval – Enter the time interval with which the interface is to be run
Timescale – Enter the timescale the interval is to operate over, i.e. seconds, minutes, hours, days or weeks
11.3.2. Locations Tab
The Locations tab allows the location that the files are to be written to once they have been generated to be defined. The files will always be written to a local directory on the database server and optionally may be written to a directory on a remote host as well.
Figure 49 -Locations tab
Local Directory UDK – Select the local directory where the files are to be written to, as defined in the Local Directories tab of the File Locations screen.
Local Directory Path – Path on the database server where the files are to be written to, as defined in the File Locations tab and automatically completed when the Local Directory UDK is selected.
Remote Directory UDK – Select the remote directory where the files are to be written to, as defined in the Remote Directories tab of the File Locations screen.
Remote Directory Path – Path on the remote server where the files are to be written to, as defined in the File Locations screen and automatically completed when the Remote Directory UDK is selected.
Page 76 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
Remote Server – Name of the remote server where the files are to be written to, as defined in the File Locations screen and automatically completed when the Remote Directory UDK is selected.
Delete Source – Only enabled when a remote directory is in use – checked means that the files are deleted from the local host after FTP transfer; unchecked means they are not deleted.
File Option – Disabled for outbound interfaces.
Move Directory UDK – Disabled for outbound interfaces.
Move Directory Path – Disabled for outbound interfaces.
11.3.3. Outbound Filters Tab
The Outbound Filters tab enables the user to place additional filters on the data that is to be exported by an outbound interface. Each filter defined will be applied against the data set that is to be exported and these will act in addition to any WHERE clauses that have been specified in the Outbound Transaction Configuration screen.
Figure 50 - Outbound Filters tab
View Column – Name of the column as defined in the Outbound Transaction Configurations screen against which the filter is to be applied.
Operator – Operator that is to be used to filter column values. The following values are available - equal to, greater than, less than, greater than or equal to, less than or equal to, between, contains, starts with, ends with, is null, is not null. ‘Contains’, ‘starts with’ and ‘ends with’ are only valid for VARCHAR2 columns. ‘Between’ will require two values to be specified, ‘is null’ and ‘is not null’ will not allow values to be specified, all other operators will
Page 77 of 78 Confidential, Enghouse Networks Ltd
API INTERFACE USER GUIDEAPI INTERFACE USER GUIDEAPI INTERFACE USER GUIDE
require one value to be specified. For date columns, values may include the string ‘:LAST_DATE’ that will get substituted at runtime for the date that the interface last ran.
Value 1 – Value to be used in filter.
Value 2 – Value to be used in filter.
Derived - Flag to show whether a VARCHAR2 or DATE value should be treated as a literal (i.e. enclosed in quotes) or derived as a SQL query. The flag cannot be set for NUMBER columns, which are always treated as derived values.
Date Format – This can only be set for view columns with a datatype of DATE, where a literal value has been specified.
11.3.4. File Naming Tab
This tab allows users to define the method by which the outbound files may be named. Note that only one file naming convention may be used to name the files from a given outbound interface.
Figure 51 - File Naming tab
Sequence – Set this to ‘1’ as only one file naming convention may be used to define outbound file names.
File Naming UDK – Select the file naming convention from the LOV that is to be applied to the files, as defined in the File Naming Conventions screen.
File Naming Description – Description of the file naming convention which is automatically completed when the File Naming UDK is selected.
Page 78 of 78 Confidential, Enghouse Networks Ltd