Business Objects

Exploring

Unlike traditional SYSPRO programs that require operator input at various stages of processing, business objects require all the necessary information before it can start processing and there is no operator input during processing.

For this reason, business objects tend to be subsets of a SYSPRO program with a very specific function (i.e. they do not necessarily match the functionality of a standard SYSPRO program).

The naming convention for business objects is similar to SYSPRO programs - six characters long, where the first three characters refer to the module and the fourth character specifies the type of business object (e.g. Query, Setup, Transaction or Build).

Some business objects contain multiple methods (e.g. the Setup classes each contain an Add, Update and Delete method) whereas others only contain one (e.g. the Transaction class has one business object for the Build method and a separate one for the Post method).

  • Business objects reside in the \Programs">\Programs folder of your SYSPRO installation.

This is a SYSPRO operator code that allows more than one e.net user to logon at the same time.

Against the operator code you configure the number of logons that must be allowed within a 30 minute time period. This effectively becomes the number of concurrent users (i.e. the number of licenses consumed when the operator is licensed to use a functional area).

Guest/anonymous user licensing is available for business objects and Web-based Applications. The idea of the guest/anonymous user is that you do not need one SYSPRO operator for each person that requires the same access to e.net Solutions. For example: if a SYSPRO company wants to provide an application to 300 customers that allows them to capture sales orders remotely and upload them using web services, they may not want to provide a license for each one, particularly since some order daily, some only order monthly and some order infrequently. By establishing how often their customers order they can work out the maximum number that could logon during any 30 minute time period. They could then create an operator to process these orders and set it to be a guest/anonymous user. Against this they can set the number of concurrent users during a 30 minute time period.

Considerations

  • If a guest/anonymous user has a concurrent user count of three, then each functional area to which the guest/anonymous user is given access will consume three licenses.

  • If a guest/anonymous user logs on to e.net Solutions, logs off and logs back on again within 30 minutes, then two licenses will have been consumed. Because this method could use more licenses than that consumed in a named user environment, we recommend that you only use this licensing method when appropriate.

  • Because each of the users that are logging on with a guest/anonymous operator code are using the same operator code, you cannot place restrictions (or set defaults) individually. All users of the operator code will have the same defaults and restrictions. You also cannot tell (using job logging, or journals) exactly which person performed a task, or made a change, as it will all be logged under the same guest/anonymous operator code.

  • A guest/anonymous user who successfully logs on to e.net Solutions is allocated a 33 character UserID which is placed in the COMSTATE file, together with its state information. Each time this user uses a business object, a timestamp is updated against the UserID in the COMSTATE file. Unlike a named user, when a guest/anonymous user exits e.net Solutions their UserID and matching state information is not removed from the COMSTATE file, but the timestamp is updated.

    When another attempt is made to logon using the same guest/anonymous user account, a check is made to see how many users of this operator code are already logged on.

    The user is allowed to logon if the number is less than the number of concurrent users allowed for this operator code.

    If the number is the same as the number allowed, then a check is made to establish which existing user of the operator code has the highest period of inactivity. If this period of inactivity is 30 minutes or greater, they are logged out and the new user logged on. If the highest period of inactivity is less than 30 minutes the new user is informed that this guest account has exceeded the maximum number of concurrent users.

  • If a guest/anonymous user is already consuming licenses for functional areas and the number of concurrent users against the operator is increased using the Operator Maintenance program, it is possible that this will cause the number of licenses to exceed those available. If this occurs, a message is displayed, indicating that you have apportioned more licenses to business objects than you are licensed to use.

A named user is a SYSPRO operator code. The business logic components of e.net Solutions are referred to as business objects. These are subdivided into functional areas (e.g. Requisition System functional area) and it is these functional areas that are licensed for the number of named users that will use them.

Unlike the core SYSPRO product, the different functional areas can be licensed for different numbers of users. For example: you could have 150 users of the Requisition System functional area and 10 users of the Purchase Order Primary Posting functional area.

Against the functional area you specify which named users can use the functional area. This allows the named user to have one concurrent logon to e.net Solutions. If another user attempts to logon to e.net Solutions (using the same operator code) while the initial user is still logged on, the existing user will either be logged off and the new user logged on, or the new user will be prevented from logging on, depending on XML parameters passed during the second logon attempt.

You can prevent the second user from logging on by supplying the following XML entry during the logon process:

<logon><FailWhenAlreadyLoggedIn>Y</FailWhenAlreadyLoggedIn></logon>

Starting

Business objects use the same security model as the core SYSPRO product. For this reason you don't need to build security into your solution. If an operator is restricted from seeing specific information within SYSPRO (e.g. costs, access to a specific warehouse, bank account details, etc.) then the XML returned by the business object will exclude this information.

The security configuration is handled from within SYSPRO and configured against the operator code, operator group, or role. You can further fine-tune these requirements using additional e.net options against the operator Activities, Electronic Signatures, Events and Triggers.

Within the Operator Groups program, the Security Access pane includes four e.net Solutions areas that you can specifically target to restrict operator access to business objects (unless the operator belongs to a group with administrator rights):

  • Module e.net Solutions - Query

  • Module e.net Solutions - Setup

  • Module e.net Solutions - Transaction

  • Module e.net Solutions - Utility

Business object entries are listed within each section and you can restrict access by ticking the relevant checkbox in the Access allowed column.

SYSPRO license details (which include e.net Solutions functional areas) are specified within the LICENSE.XML file that accompanies your initial software purchase and any upgrade to your existing software. If at any stage you change your number of SYSPRO users, modules, functional areas, or renew your annual license, you receive a new LICENSE.XML file.

The e.net Solutions section of the LICENSE.XML file is imported using the Configure e.net License function of the System Setup program. This loads a wizard that guides you through the process of importing functional area licenses and apportioning them to specific operator codes.

Option Description

Import LICENSE.XML file

Select this to import the LICENSE.XML file that by default resides in the \Work folder of your SYSPRO installation.

Configure e.net licenses

Business Objects

This displays the Apportion e.net Licenses window for you to apportion licenses to operators that will use functional areas of Business Objects.

Web-based Applications

This displays the Apportion e.net Licenses window for you to you to apportion licenses to operators that will use functional areas of the Web-based Applications.

Maintain e.net Classes

This enables you to configure groups of users who are licensed to use the Web-based Applications.

You typically use this method of licensing if you know that the number of concurrent Web-based Application users is significantly less then the total number of users who will ever use the application.

Solving

A business object can return errors as exceptions or as messages in the XML.

An exception indicates an error that prevents the business object from continuing processing. This can be caused by a number of conditions:

  • Attempting to logon with an invalid value (e.g. the operator is invalid).

  • The supplied UserID is not valid/no longer valid.

  • Calling a Query or Build business object and the supplied key value is not valid (e.g. when using either the ARSQRY or SORRSH business objects and the supplied customer account number is invalid).

  • A file error is reported (e.g. corrupt file index).

  • A parsing error occurs when SYSPRO is processing the supplied XML (e.g. the supplied closing element name does not match the opening element name).

  • The debug option is set during the logon and one of the XML element names is invalid for the business object (e.g. the customer maintenance business object - APRSSCS - is called using the Update method, and the supplied customer does not exist).

Indicating errors messages within the XML returned from a business object is useful in that more than one message can be returned at a time. This avoids the developer having to resubmit the XML after correcting each issue that is detected.

Messages returned within the XML can be warnings or errors, where a warning indicates a problem that does not affect processing and an error prevents you from continuing

Most Post method, and Setup class business object include the <IgnoreWarnings> element within the parameter XML string which allows you to manipulate the behavior of these messages.

A value of N indicates that all warnings must appear as error messages; a value of Y indicates that messages relating to warnings must not be included in the returned XML and a value of W indicates that all warning messages must have a <WarningNumber> element instead of an <ErrorNumber> element and a <WarningDescription> element instead of a <ErrorDescription> element. The values against these elements will still be the same.

The W alue enables a developer to search through the returned XML looking to see if there are any errors that will prevent the posting from happening (i.e. those with an <ErrorNumber> element). They can also search through the returned XML looking for any warnings (i.e. those with a <WarningNumber> element.

The English error messages are stored in four text files within the \Programs folder of the SYSPRO application server. These are called:

  • MSGCOMEN.IMP

  • MSGDISEN.IMP

  • MSGFINEN.IMP

  • MSGMANEN.IMP

The structure of an error message filename is that it begins with MSG, the next three letters relate to the SYSPRO development area (COMmen, FINancials, DIStribution, and MANufacturing), followed by the two letter language code used during the e.net Solutions logon (where EN is for English).

Using

To use a business object outside of SYSPRO it must be licensed and you must first logon to e.net Solutions (using the Logon method that forms part of the Utilities class).

If the logon to e.net Solutions is successful, a 34-character UserID is returned. This UserID must be supplied each time the business object is called and must be valid. The business object is accessed using the permissions associated with the operator who performed the logon.

The 34-character UserID comprises a 32-character GUID followed by a single digit e.net Solutions instance number (i.e. the instance of e.net Solutions to use if more than one copy resides on the machine) and a final digit indicating the type of user 0 indicates a normal e.net Solutions user, while 1 or 2 indicates one of two possible SYSPRO Espresso users).

When you perform the logon there are eight items of information that you can provide. Some are mandatory (e.g. SYSPRO operator code) but most are either optional or can be configured to a default setting.

Logon information Description
Operator

This must be a valid SYSPRO operator code. Depending on setup options, this may also be a network user login.
Operator Password This is the password that matches the operator code.
Company ID This is the company to which you want to logon. If a default company is configured against this operator code then it will be used if you do not supply a company ID.
Company Password This is the password for this company ID.
Language Code

This is the language code used for error and information messages. If you do not supply a language code, then the code held against the operator is used. If language files do not exist for this language code it defaults to English. Valid codes are: EN (English) FR (French) ES (Spanish) and ZH (Simplified Chinese).

Prior to SYSPRO 6.1, language codes were numeric (e.g. 05, 07, 12, and 15 respectively). This functionality has been retained for backwards compatibility (i.e. if you logon using these numeric language codes it will continue to work).

This language code is also used for menus and screens if you are performing a logon to the e.net Solutions Web-based Applications. The Log Level can be 0 or 1 (where 1 indicates that invalid elements are reported and 0 ignores elements that are invalid).
SYSPRO Instance This indicates the BaseDir entry to use from the Windows Registry (i.e. which copy of SYSPRO and data to use).
XMLIn Additional parameters can be supplied within an XML string at logon time to affect how e.net Solutions interacts with the user while logged in.

XMLIn parameters

Parameter Description
<Logon> This is the root element.
<Siteid>

This element supplies the identification code of a site. This is sometimes used by SYSPRO to activate functionality that is only applicable when a specific site code is present (e.g. an Early Adopter who is testing the functionality before it is available on general release).
<FailWhenAlreadyLoggedIn>

A value of Y for this element will preserve the admstate of a UserID that is already logged in. Otherwise, the original operator is logged out and the UserID removed from the admstate file.

<BuildToPost>

This element informs a Build method business object to return the XML output with its element names by the matching Post business object.
<SourceApp>

This element accepts a 30-character string that describes the application in use. It is intended for future use. For example, SYSPRO's Electronic Signatures system will provide a mechanism for using a $SourceApp system variable in conditional statements, detail logging, and email notifications.
<SystemInformationReqd>

This element causes additional information to be returned by a business object within a <SystemInformation> node (e.g. company name, operator group, currency, etc). In addition, items that would normally be returned as attributes of the root element (e.g. language, decimals, role, business object version, etc.) are returned as elements within the <SystemInformation> node.
<DefaultRole>

This element enables an operator (who belongs to multiple roles) to override their primary role by supplying the 3-digit role number.

In the core SYSPRO product an operator can change roles using the Switch Roles option on the Home tab of the Ribbon bar. You can establish the role number using the Role Management program. By default, the Role column does not appear in the list view, but you can use the Field Chooser function to add it. The Field Chooser is available from the shortcut menu that is displayed when you right-click a column header.
<NameSpaceReqd>

This caters for elements that have the same name across different tables in the database, by declaring namespaces as attributes against the root element (i.e. the element name is prefixed with the namespace).

The namespace used is a 6-character file code for the table name (e.g. SALSLS for Sales Analysis Salesperson table which will appear as xmlns:SALSLS="SALSLS" against the root element of a business object).

Columns that are duplicated but which come from the primary table used by the business object will appear without a namespace.

Duplicated columns from all other tables will have namespaces (e.g. the ARSQRY business object needs to return Name elements with values from both the Customer Master table and the Salesperson table, so it writes out the one from the Customer Master table as <Name> and the one from the Salesperson table as <SALSLS:Name>.

Set the <NameSpaceReqd> element to N if your application does not cater for namespaces.

This removes the namespace attributes from the root element and replaces the colon between the namespace and the element name with an underscore (i.e. effectively making this just an element name). So the <SALSLS:Name> element would become <SALSLS_Name>.

Unlike the core SYSPRO product (that can be launched from a desktop or menu shortcut which contains entries to locate the \Base folder and SYSPRO executable and components) e.net Solutions requires an entry in your Windows Registry to establish the location of your SYSPRO \Base folder.

During a typical SYSPRO installation, an entry is created in your Windows Registry that specifies the location of your SYSPRO \Base folder. The entry that is created is called BaseDir and it exists within a key called e.net solutions.

It is possible to install multiple copies of SYSPRO on the SYSPRO application server. This is typically done in a test or support environment, where each install is a different version. To cater for each of these copies having their own instance of e.net Solutions, the e.net solutions Registry key allows for multiple BaseDir entries (i.e. up to BaseDir9

An instance number is assigned to each BaseDir entry:

BaseDir entry Description
BaseDir 0
BaseDir1 1
BaseDir2 2
BaseDir3 3

When you log in to e.net Solutions and receive the UserID, entries are written to the AdmState table in SYSPRO's system database.

This table retains state information for each user, such as the company settings at the time they logged on, their operator permissions, restrictions, etc.

The table's key is the UserID. When you log off from e.net Solutions, the entries relating to this UserID are removed from the AdmState table. When you call a business object from outside of SYSPRO you must supply a valid UserID.