Fourth Shift Transactional Interface Fourth Shift Release 7.50

Transcription

1 Fourth Shift Transactional Interface Fourth Shift Release 7.50

2 Fourth Shift Help 2008, Release SoftBrands, Inc. All rights reserved This documentation is copyrighted and all rights are reserved. This documentation may not, in whole or in part, be reproduced in any form. SoftBrands, Inc. provides this publication as is without warranty of any kind, either expressed or implied, including but not limited to the implied warranties or conditions of merchantability or fitness for a particular purpose. In no event shall SoftBrands, Inc. be liable for any loss of profits, loss of business, loss of use of data, interruption of business, or for direct, special, incidental, or consequential damages of any kind, even if SoftBrands, Inc. has been advised of the possibility of such damages arising from any defect or error in this publication. Fourth Shift is a registered trademark of SoftBrands, Inc. Microsoft, SQL Server, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Crystal Reports is a registered trademark of Crystal Decisions, Inc. in the U.S. and/or other countries. FSTransactional Interface 2

3 Contents Fourth Shift Transactional Interface Module The FourthShift.Transactions Class Library The FourthShift.TransactionsClient Class Library Organization of This Manual FourthShift.Transactions Developer Guide Programming Example Description Referencing the Class Library Variable Declarations Setting Properties Retrieving the Transaction String Retrieving the Required Field Names Retrieving the Required Field Numbers Retrieving the Eligible Field Numbers Using RequiredFieldsSet Using the TransactionField Object Generically Reverse Mapping a Transaction String FourthShift.TransactionClient Developer Guide Programming Example Description Referencing the Class Libraries Variable Declarations Initialization Part Initialization Part Logon SubmitItem Handler DumpErrorObject Calling Terminate FourthShift.Transactions API ITransaction Interface ITransactionField Interface TransactionFactory Class FourthShift.TransactionClient API FSTIClient FSTIError Class FSTIApplicationException Class FSTI System Administration Fourth Shift Remoting Service Impersonation FSTransactional Interface 3

4 Fourth Shift Transactional Interface Module The Fourth Shift Transactional Interface module (FSTM) allows you to update the Fourth Shift production database without using the traditional GUI or the Import feature. In FSTM, standard Fourth Shift data entry rules are enforced in using an API that can accept transactions from your other applications. The FSTI Software Development Kit (SDK) is a resource that you can reference as you construct Fourth Shift archive format transactions to be processed into Fourth Shift using FSTM. This SDK is a set of class libraries that provides a simple but powerful mechanism for developing applications that can insert, delete or update Fourth Shift systems in real-time. Using the FSTI SDK, programmers can write custom interactive programs and web applications to automate many common tasks or develop applications to combine Fourth Shift functions with external applications. The FSTI SDK supports most standard development languages such as Visual Basic, C#, VB.NET and scripting languages. All applications using the FSTI SDK will follow a very similar pattern, first an initialization step including a logon because the SDK enforces Fourth Shift security. Then, after a successful logon, applications submit transaction requests and receive back immediate success or failure responses. After a success or failure, the FSTI SDK provides additional return information that allows programmers to take appropriate follow-up actions. One form that transaction requests can take (but the hardest to work with) are standard Fourth Shift recovery (RCVR) or SOP import strings in comma delimited format (CDF). An alternative, and substantially easier method than forming a CDF string, is to use one of the transaction classes found in the FourthShift.Transactions class library. The FourthShift.Transactions Class Library Using the classes found in the FourthShift.Transactions library, programmers can concentrate on setting class properties and not have to worry about generating proper comma delimited string. This class library contains a specific class for each type of transaction that is supported either by Fourth Shift RCVR or SOP Import. For example, to insert a new item into Fourth Shift, an application can form a complex string like ITMB00,,, NewItem, New Item Description,,,, or, alternatively, the application can instantiate an ITMB00 object from the FourthShift.Transactions class library, set several of its properties such as ItemNumber and ItemDescription and then submit the ITMB00 transaction object for processing. The FourthShift.TransactionsClient Class Library A second class library, FourthShift.TransactionClient is used for processing transactions. FSTIClient is its main class and it has two methods, ProcessCDF and ProcessID that accept CDF transaction strings or Transaction objects respectively. FSTIClient uses.net Remoting technology to pass requests to the server for high speed processing. After processing transactions, the server sends back success or failure information to the client. Organization of This Manual This manual is organized into the following sections to assist programmers in using the classes found in the FourthShift.Transactions and the FourthShift.TransactionClient libraries. FSTransactional Interface 4

5 FourthShift.Transactions Developer Guide FourthShift.Transaction Client Developer Guide FourthShift.Transactions API FourthShift.Transaction Client API FSTI System Administration Programming guide for the FourthShift.Transactions class library. It uses a sample program to demonstrate using the classes in the library. Programming guide for the FourthShift.TransactionClient class library. It uses a sample program to present the main features of the FSTIClient class and the associated FSTIError class from the FourthShift.TransactionClient library. Reference manual for the FourthShift.Transactions library. Contains detailed information on all the properties and methods for the classes in the library. Reference manual for the FourthShift.TransactionClient library. Contains detailed information on all the properties and methods for the classes in the library. Administrative information on the FSTI SDK. Of particular importance in this section is the Impersonation configuration information. FSTransactional Interface 5

6 FourthShift.Transactions Developer Guide FourthShift.Transactions Developer Guide The FourthShift.Transactions class library provides a consistent and easy to use programming interface for generating and manipulating the transactions supported by Fourth Shift RCVR and SOP import. Classes in the library are based on Fourth Shift s Data Import Dictionary and SOP s Import Dictionary. The classes in the library are particularly useful when used in combination with the FSTIClient object for immediate real-time processing, but can also be used stand-alone for generating comma delimited format (CDF) transaction strings that are written into files that are later destined for RCVR or SOP import. Classes in the library are named by their familiar 6 character identifier, for example, ITMB00 is a class that can be used to create a new item, MOMT00 can be used to create a new manufacturing order header, COMT00 inserts a new customer order header, COMT05 adds a customer order line, and SOPO00 creates an SOP order header. The class library contains hundreds of transaction classes, one for each transaction defined in the Fourth Shift or SOP Import dictionaries. Most properties of a class, such as ITMB00 s ItemNumber and ItemDescription correspond to fields in the comma delimited format that the class is based on. The names for the properties of the transaction classes are based on the Fourth Shift SQL Foundation Business View Names because those names are descriptive and generally easy to understand. To make this more concrete, here are the complete set of properties for the ITMB00 class: Category, Description, IsInspectionRequired, IsLotTraced, IsSerialized, ItemDescription, ItemNumber, ItemRevision, ItemStatus, ItemType, ItemUM, MakeBuyCode, Name, OrderPolicy, RequiredAreSet And here are the properties for the MOMT00 class: Category, DeliverTo, Description, MONumber, Name, Planner, RequiredAreSet, TextLine1, TextLine2, TextLine3, TextLine4, WorkCenter There are properties that are shared by all transaction classes, such as Category, Description, and RequiredAreSet. The remaining fields are particular to the type of the transaction, such as ItemNumber and ItemUM for ITMB00 and MONumber for MOMT00. An application creates an instance of the class, sets fields such as ItemNumber, ItemDescription, ItemUM, and then can either retrieve a properly formatted string from the object, using the object s GetString method, or the object can be passed to an FSTIClient object for processing. Programming Example Description This example will work through a sample program named ItmbObject that uses the FSTransaction class library to manipulate first an ITMB00 object and then an MOMT03 object. If the FSTM module is installed, the source code can be found in the directory, \mfgsys\fstm\sdk Sample Code off the root of the Fourth Shift installation. The sample program is a simple console application in C# and VB.NET while the VB6 uses a list box to simulate the console window. Referencing the Class Library To access the FourthShift.Transactions library, C# and Visual Basic.NET programmers need to add a reference to the assembly at the location: Program Files => Fourth Shift => Managed = > FourthShift.Transactions.dll FSTransactional Interface 6

7 FourthShift.Transactions Developer Guide This copy of the library is for programming purposes only, the project reference setting for copy local should be set to false because the run-time dll is actually in the global assembly cache (GAC) placed there as part of the Fourth Shift workstation install. VB6 coders need to add a reference to: Fourth Shift Transaction Library Once the reference is established, C# and VB.NET coders need to add the appropriate using or imports statements. [C#] using System; using System.Collections; using SoftBrands.FourthShift.Transaction; [VB.Net] Imports System Imports System.Collections Imports SoftBrands.FourthShift.Transaction Variable Declarations Since the sample application is a console application, the code is organized as one large subroutine with most of the variable declarations at the top (the VB6 code is all contained in the form load handler). Here are the variable declarations for the first part of the program followed by a description of the purpose of each of the variables. [C#] ITMB00 myitem = new ITMB00(); string transactionstring; ITransactionField currentfield; string[] itemrequiredfieldnames; int[] itemrequiredfieldnumbers; int[] itemeligiblefieldnumbers; int i; [VB.Net] Dim myitem As ITMB00 = New ITMB00 Dim transactionstring As String Dim currentfield As ITransactionField Dim itemrequiredfieldnames As String() Dim itemrequiredfieldnumbers As Int32() FSTransactional Interface 7

8 FourthShift.Transactions Developer Guide Dim itemeligiblefieldnumbers As Int32() Dim i As Int32 [VB6] Dim myitem As ITMB00 Set myitem = New ITMB00 Dim transactionstring As String Dim currentfield As ITransactionField Dim itemrequiredfieldnames() As String Dim itemrequiredfieldnumbers() As Long Dim itemeligiblefieldnumbers() As Long Dim i As Long The first line creates a ITMB00 object and the next variable, transactionstring, will be used to eventually hold a properly formatted ITMB00 CDF transaction string. The next variable declared, currentfield, is of type ITransactionField. The type TransactionField and its interface ItransactionField are key concepts when using the class library. Most properties of the ITMB00 class correspond to fields in the original CDF string. These properties all derive from a common object, TransactionField that has the interface ITransactionField. This means that these properties all share common properties such as Value and Type and it also makes it possible to code generically as shown below using VB.Net syntax: currentfield = myitem.itemnumber currentfield references ItemNumber currentfield = myitem.itemdescription currentfield now references ItemDescription In a very similar fashion, all transaction classes such as ITMB00 and MOMT00 are derived from the class TransactionId that implements the interface ITransaction making the following generic code possible: Dim currenttransaction as ITransaction currenttransaction = new ITMB00 currenttransaction references a ITMB00 transaction object currenttransaction = new MOMT00 currenttransaction now references a MOMT00 transaction object The next three variables are used to hold return values from methods implemented by all the classes that are derived from TransactionId. The itemrequirednames will receive an array of the names of the fields that must be set in order for a transaction to be a valid input for an RCVR or SOP Import. The itemrequiredfieldnumbers will hold the same information, but instead of the names of the fields it will receive the positions of the required fields in the transaction string. Typically all the field positions in a FSTransactional Interface 8

9 FourthShift.Transactions Developer Guide transaction string are not valid, most properly formatted transaction strings have many positions that will be left empty. The itemeligiblefieldnumbers receives the results of calling a method that identifies the positions of the fields that can be filled in. The EligibleFieldsNumbers are always a superset of the RequiredFieldNumbers. Setting Properties The following code sets the properties of the myitmb00 object. Recall that each property, such as ItemNumber, is a reference to a object implementing the ITransactionField interface, requiring the syntax.value for storing and retrieving the actual setting. [C#] myitem.itemnumber.value = "19-BLACK"; myitem.itemdescription.value = "19\" FRAME, BLACK"; myitem.itemum.value = "EA"; myitem.itemrevision.value = "01"; myitem.makebuycode.value = "M"; myitem.itemtype.value = "N"; myitem.itemstatus.value = "A"; myitem.islottraced.value = "N"; myitem.isserialized.value = "N"; myitem.orderpolicy.value = "3"; myitem.isinspectionrequired.value = "Y"; [VB.Net] With myitem.itemnumber.value = "19-BLACK".ItemDescription.Value = "19"" FRAME, BLACK".ItemUM.Value = "EA".ItemRevision.Value = "01".MakeBuyCode.Value = "M".ItemType.Value = "N".ItemStatus.Value = "A".IsLotTraced.Value = "N".IsSerialized.Value = "N".OrderPolicy.Value = "3".IsInspectionRequired.Value = "Y" End With FSTransactional Interface 9

10 FourthShift.Transactions Developer Guide [VB6] With myitem.itemnumber.value = "19-BLACK".ItemDescription.Value = "19"" FRAME, BLACK".ItemUM.Value = "EA".ItemRevision.Value = "01".MakeBuyCode.Value = "M".ItemType.Value = "N".ItemStatus.Value = "A".IsLotTraced.Value = "N".IsSerialized.Value = "N".OrderPolicy.Value = "3".IsInspectionRequired.Value = "Y" End With Retrieving the Transaction String The next line of code shows the retrieval of the ITMB00 transaction as a comma delimited string. An enumerated type is passed in that specifies the desired format. The code below passes in TransactionStringFormat.fsCDF to get a CDF string. An alternative is to request an XML string using TransactionStringFormat.fsXML. [C#] // Retrieve the transaction string from the Itmb00 object transactionstring = myitem.getstring(transactionstringformat.fscdf); Console.WriteLine("===Transaction String===\n"); Console.WriteLine(transactionString); Console.WriteLine(); [VB.Net] ' Retrieve the transaction string from the Itmb00 object transactionstring = myitem.getstring(transactionstringformat.fscdf) Console.WriteLine("===Transaction String===" & vbcrlf) Console.WriteLine(transactionString) Console.WriteLine() [VB6] ' Retrieve the transaction string from the Itmb00 object FSTransactional Interface 10

11 FourthShift.Transactions Developer Guide transactionstring = myitem.getstring(transactionstringformat_fscdf) listoutput.additem "===Transaction String===" listoutput.additem "" listoutput.additem transactionstring listoutput.additem "" The output from this portion of the code is: ===Transaction String=== "ITMB00","","11/05/2003","018:10:25","0","","19-BLACK","19" FRAME, BLACK","EA","01","M","N","A","N","N","3","Y" The GetString method will fill in the current date and time for positions 3 and 4 of the transaction string. Retrieving the Required Field Names All transaction classes have a GetRequiredFieldNames method that returns the names of the required fields. This code demonstrates retrieving those names. For some transactions there are fields that may be required depending on configuration, for example if an item is lot traced. Fields that may be required are not returned by this function, only fields that are always required. [C#] // Get the required field names from the Itmb00 object itemrequiredfieldnames = myitem.getrequiredfieldnames(); Console.WriteLine("===Required Fields Names===\n"); for (i=0; i < itemrequiredfieldnames.length; i++ ) { Console.WriteLine(" FieldName: {0}", itemrequiredfieldnames[i]); } Console.WriteLine(); [VB.Net] ' Get the required field names from the Itmb00 object itemrequiredfieldnames = myitem.getrequiredfieldnames() Console.WriteLine("===Required Fields Names===" & vbcrlf) For i = 0 To itemrequiredfieldnames.length - 1 Console.WriteLine(" FieldName: {0} ", itemrequiredfieldnames(i)) Next i Console.WriteLine() FSTransactional Interface 11

12 FourthShift.Transactions Developer Guide [VB6] ' Get the required field names from the Itmb00 object itemrequiredfieldnames = myitem.getrequiredfieldnames() listoutput.additem "===Required Fields Names===" listoutput.additem "" For i = 0 To UBound(itemRequiredFieldNames) listoutput.additem " FieldName: " & itemrequiredfieldnames(i) Next i listoutput.additem "" The output from this code section of the code is: ===Required Fields Names=== FieldName: ItemNumber The only required field for ITMB00 is the ItemNumber field, all other fields are optional. Retrieving the Required Field Numbers Instead of the required field names, the following code uses the GetRequiredFieldNumbers method to display the required positions of the fields in the comma delimited. The only required position is position 7 for the ItemNumber as shown in the output. [C#] // Get the required field numbers (the positions in the transaction string // that are required) itemrequiredfieldnumbers = myitem.getrequiredfieldnumbers(); Console.WriteLine("===Required Fields Numbers===\n"); for (i=0; i < itemrequiredfieldnumbers.length; i++ ) { Console.WriteLine(" FieldNumber: {0}", itemrequiredfieldnumbers[i]); } Console.WriteLine(); [VB.Net] FSTransactional Interface 12

13 FourthShift.Transactions Developer Guide ' Get the required field numbers (the positions in the transaction string ' that are required) itemrequiredfieldnumbers = myitem.getrequiredfieldnumbers() Console.WriteLine("===Required Fields Numbers===" & vbcrlf) For i = 0 To itemrequiredfieldnumbers.length - 1 Console.WriteLine(" FieldNumber: {0}", itemrequiredfieldnumbers(i)) Next i Console.WriteLine() [VB6] ' Get the required field numbers (the positions in the transaction string ' that are required) itemrequiredfieldnumbers = myitem.getrequiredfieldnumbers() listoutput.additem ("===Required Fields Numbers===" & vbcrlf) For i = 0 To UBound(itemRequiredFieldNumbers) listoutput.additem " FieldNumber: {0}", itemrequiredfieldnumbers(i) Next i listoutput.additem "" The output from this code section of the code is: ===Required Fields Numbers=== FieldNumber: 7 Retrieving the Eligible Field Numbers The GetEligibleFieldNumbers method is used to determine the field positions in the comma delimited transaction string that can be specified. Many transaction strings have fields that should not be filled in. [C#] // Get the eligible field numbers (the positions that are valid (can be set) in // the transaction string. Not all positions are valid, some should be left empty itemeligiblefieldnumbers = myitem.geteligiblefieldnumbers(); Console.WriteLine("===Eligible Fields Numbers==="); for (i=0; i < itemeligiblefieldnumbers.length; i++ ) FSTransactional Interface 13

14 FourthShift.Transactions Developer Guide { Console.WriteLine(" FieldNumber: {0}, Name: {1}", itemeligiblefieldnumbers[i], myitem.get_field(itemeligiblefieldnumbers[i]).name); } Console.WriteLine(); [VB.Net] ' Get the eligible field numbers (the positions that are valid (can be set) in ' the transaction string. Not all positions are valid, some should be left empty itemeligiblefieldnumbers = myitem.geteligiblefieldnumbers() Console.WriteLine("===Eligible Fields Numbers===") For i = 0 To itemeligiblefieldnumbers.length - 1 Console.WriteLine(" FieldNumber: {0}, Name: {1}", _ itemeligiblefieldnumbers(i), myitem.field(itemeligiblefieldnumbers(i)).name) Next i Console.WriteLine() [VB6] ' Get the eligible field numbers (the positions that are valid (can be set) in ' the transaction string. Not all positions are valid, some should be left empty itemeligiblefieldnumbers = myitem.geteligiblefieldnumbers() listoutput.additem "===Eligible Fields Numbers===" For i = 0 To UBound(itemEligibleFieldNumbers) listoutput.additem " FieldNumber: " & itemeligiblefieldnumbers(i) & _ ", Name: " & myitem.field(itemeligiblefieldnumbers(i)).name Next i listoutput.additem "" The output from this code section of the code is: FSTransactional Interface 14

15 FourthShift.Transactions Developer Guide ===Eligible Fields Numbers=== FieldNumber: 7, Name: ItemNumber FieldNumber: 8, Name: ItemDescription FieldNumber: 9, Name: ItemUM FieldNumber: 10, Name: ItemRevision FieldNumber: 11, Name: MakeBuyCode FieldNumber: 12, Name: ItemType FieldNumber: 13, Name: ItemStatus FieldNumber: 14, Name: IsLotTraced FieldNumber: 15, Name: IsSerialized FieldNumber: 16, Name: OrderPolicy FieldNumber: 17, Name: IsInspectionRequired The output shows the positions that are valid, 7 through 17, and the names of each of the properties corresponding to each field position. Using RequiredFieldsSet Transaction classes have a property, RequiredFieldsSet that returns true if all the required field positions are set, and returns false otherwise. Applications can use this property to avoid creating or submitting transactions that are not complete. Only fields that are always required are detected, fields that may be required, such as transactions involving items that are lot traced are not included and this method can return false positives for those cases. The code below shows calling this property and the output of true since the required field ItemNumber has been set for this object. [C#] // The RequiredAreSet property indicates if all the required properties have been // set, there is no point in submitting a transaction if all the fields are not set Console.WriteLine("\nRequired are set = {0}\n", myitem.requiredareset ); [VB.Net] ' The RequiredAreSet property indicates if all the required properties have been ' set, there is no point in submitting a transaction if all the fields are not set Console.WriteLine(vbCrLf & "Required are set = {0}" & vbcrlf, myitem.requiredareset) [VB6] FSTransactional Interface 15

16 FourthShift.Transactions Developer Guide ' The RequiredAreSet property indicates if all the required properties have been ' set, there is no point in submitting a transaction if all the fields are not set listoutput.additem "" listoutput.additem "Required are set = " & myitem.requiredareset Using the TransactionField Object Generically All properties that correspond to fields in the transaction string are of type TransactionField and can be referenced by the interface ITransactionField. The following code demonstrates treating the properties generically by assigning the currentfield variable first to ItemNumber and then to ItemDescription. [C#] // This code demonstrates how all properties are of the same type, TransactionField // and can be treated generically. currentfield will first be set to the ItemNumber // then set to ItemDescription currentfield = (ITransactionField) myitem.itemnumber; Console.WriteLine("currentFields references property: {0}, value is: {1}", currentfield.name, currentfield.value ); currentfield = (ITransactionField) myitem.itemdescription; Console.WriteLine("currentFields references property: {0}, value is: {1}", currentfield.name, currentfield.value ); [VB.Net] ' This code demonstrates how all properties are of the same type, TransactionField ' and can be treated generically. currentfield will first be set to the ItemNumber ' then set to ItemDescription currentfield = DirectCast(myItem.ItemNumber, ITransactionField) Console.WriteLine("currentFields references property: {0}, value is: {1}", _ currentfield.name, currentfield.value) FSTransactional Interface 16

17 FourthShift.Transactions Developer Guide currentfield = DirectCast(myItem.ItemDescription, ITransactionField) Console.WriteLine("currentFields references property: {0}, value is: {1}", _ currentfield.name, currentfield.value) [VB6] ' This code demonstrates how all properties are of the same type, TransactionField ' and can be treated generically. currentfield will first be set to the ItemNumber ' then set to ItemDescription Set currentfield = myitem.itemnumber listoutput.additem "currentfields references property: " & currentfield.name & _ "value is: " & currentfield.value Set currentfield = myitem.itemdescription listoutput.additem "currentfields references property: " & currentfield.name & _ "value is: " & currentfield.value Reverse Mapping a Transaction String The FourthShift.Transactions class library includes a class TransactionFactory, that can reverse map transaction strings from their comma delimited format into the correct Transaction object. The following code demonstrates taking a hard-coded MOMT03 assigning it to the string variable input, creating a TransactionFactory object and then calling TransactionFactory s CreateTransactionFromCDF method to return an MOMT03 transaction object. [C#] String input = "\"MOMT03\",\"AAA\",\"11/04/ 2003\",\"010:01:03\",\"0\",\"A\",\"T\",\"MO1\",\"AAA\", \"110403\",\"000000\",\"\",\"\""; TransactionFactory factory = new TransactionFactory(); ITransaction transaction = factory.createtransactionfromcdf( input ); Console.WriteLine("\n===Transaction String Parsing Example===\n"); FSTransactional Interface 17

18 FourthShift.Transactions Developer Guide Console.WriteLine("Input String:\n"); Console.WriteLine(input); Console.WriteLine("\n===After Parsing===\n"); Console.WriteLine("Transaction object name: {0}\n", transaction.name); [VB.Net] Dim input As String = _ """MOMT03"",""AAA"",""11/04/ 2003"",""010:01:03"",""0"",""A"",""T"",""MO1"",""AAA"", ""110403"",""000000"","""",""""" Dim factory As TransactionFactory = New TransactionFactory Dim transaction As ITransaction = factory.createtransactionfromcdf(input) Console.WriteLine(vbCrLf & "===Transaction String Parsing Example===" & vbcrlf) Console.WriteLine("Input String:" & vbcrlf) Console.WriteLine(input) Console.WriteLine(vbCrLf & "===After Parsing===" & vbcrlf) Console.WriteLine("Transaction object name: {0}" & vbcrlf, transaction.name) [VB6] Dim strinput As String strinput = _ """MOMT03"",""AAA"",""11/04/ 2003"",""010:01:03"",""0"",""A"",""T"",""MO1"",""AAA"", ""110403"",""000000"","""",""""" Dim factory As New TransactionFactory Dim transaction As ITransaction Set transaction = factory.createtransactionfromcdf(strinput) listoutput.additem "" listoutput.additem "===Transaction String Parsing Example===" FSTransactional Interface 18

19 FourthShift.Transactions Developer Guide listoutput.additem "" listoutput.additem "Input String:" listoutput.additem "" listoutput.additem strinput listoutput.additem "" listoutput.additem "===After Parsing===" listoutput.additem "" listoutput.additem "Transaction object name: " & transaction.name listoutput.additem "" The output from the code is below. Note that the code above does not have to know in advance the type of the Transaction object that is returned, it just uses a variable of type ITransaction to hold a reference to the returned object. It can then interrogate the object to determine the type, as it does above using the Name property to see that it is an MOMT03 object. Output: Input String: "MOMT03","AAA","11/04/ 2003","010:01:03","0","A","T","MO1","AAA","110403","000000","","" ===After Parsing=== Transaction object name: MOMT03 The sample application concludes by printing out all the eligible fields of the MOMT03 object showing their assigned valued after parsing the input string. The code and output follow: [C#] // Print out the eligible fields names and values int[] eligiblefieldnumbers = transaction.geteligiblefieldnumbers(); Console.WriteLine("===Eligible Field Current Values===\n"); for (i=0; i < eligiblefieldnumbers.length; i++ ) { int fieldnumber = eligiblefieldnumbers[i]; Console.WriteLine(" FieldName: {0}, Value: {1}", transaction.get_field(fieldnumber).name, FSTransactional Interface 19

20 FourthShift.Transactions Developer Guide } transaction.get_field(fieldnumber).value); [VB.Net] ' Print out the eligible fields names and values Dim eligiblefieldnumbers As Int32() = transaction.geteligiblefieldnumbers() Console.WriteLine("===Eligible Field Current Values===" & vbcrlf) For i = 0 To eligiblefieldnumbers.length - 1 Dim fieldnumber As Int32 = eligiblefieldnumbers(i) Console.WriteLine(" FieldName: {0}, Value: {1}", _ transaction.field(fieldnumber).name, _ transaction.field(fieldnumber).value) Next i [VB6] ' Print out the eligible fields names and values Dim eligiblefieldnumbers() As Long eligiblefieldnumbers = transaction.geteligiblefieldnumbers() listoutput.additem "===Eligible Field Current Values===" listoutput.additem "" For i = 0 To UBound(eligibleFieldNumbers) Dim fieldnumber As Long fieldnumber = eligiblefieldnumbers(i) listoutput.additem " FieldName: " & transaction.field(fieldnumber).name & _ " Value: " & transaction.field(fieldnumber).value Next i The output from this code section of the code is: ===Eligible Field Current Values=== FieldName: MONumber, Value: MO1 FieldName: Planner, Value: AAA FieldName: WorkCenter, Value: FSTransactional Interface 20

21 FourthShift.Transactions Developer Guide FieldName: DeliverTo, Value: FieldName: TextNumber, Value: FSTransactional Interface 21

22 FourthShift.TransactionClient Developer Guide FourthShift.TransactionClient Developer Guide The FourthShift.TransactionClient class library contains the classes used for submitting transactions to Fourth Shift and for receiving back immediate success or failure information. The class library is implemented using Microsoft.NET technologies and supports.net languages such as C# and VB.NET and also Visual Basic 6.0 through.net s sophisticated COM interoperability capabilities. The main class in the library is FSTIClient. Program flow for an application using FSTIClient consists of: 1. Creating a new FSTIClient object. 2. Initializing the FSTIClient object. 3. Performing a successful logon. 4. Forming a transaction string. 5. Processing the transaction. 6. On error, accessing the FSTIError object to determine the problem. Step 4 can be made substantially easier through the use of transaction classes as described in Section 2. Logon and transaction processing actually take place on the Fourth Shift server, FSTIClient is mainly a proxy stub program that uses.net remoting to communicate with the server. Step 2, initialization, establishes a connection between the client and a Windows Service running on the Fourth Shift server named Fourth Shift Remoting Service. The Fourth Shift Remoting Service starts a dedicated FSGuiApp.exe process for each connected FSTIClient object. FSTIClient supports both Fourth Shift RCVR transactions and SOP import transactions. The first time an SOP transaction is requested by an application the Remoting Service will establish a dedicated SOPTIServer.exe process for that connection to handle SOP requests. Applications using FSTIClient can optionally participate in Fourth Shift unified logon. Unified logon means that if a prior Fourth Shift application is detected as having already been started on the workstation, then the FSTIClient application can skip step 3 and use the UserId of the application that is already logged on that workstation. Unified logon is useful for creating applications that seamlessly integrate with other Fourth Shift applications running on the client desktop. The user only has to logon once, when the first Fourth Shift application is started, and never has to logon again. Typically, unified logon should not be used by web applications since it creates a situation where all users connected to the web server share the same user id without requiring each of them to logon. Unified logon is controlled by each application based on a flag that is passed to the FSTIClient Initialize method as will be shown in the sample application that follows. Note that for Fourth Shift license planning, each unique logon consumes a Fourth Shift license. Thus an FSTIClient application using unified logon will be sharing a license with the other Fourth Shift applications running on that workstation. FSTIClient accepts two transaction formats: a comma delimited string and a Transaction object from FourthShift.Transactions class library. FSTIClient will be supporting an XML format in a future release. Programming Example Description This document works through a simple windows form program that uses FSTIClient and the ITMB00 class from the FourthShift.Transactions library to add a new item to the Fourth Shift system. The discussion that follows assumes that the reader is familiar with the material in section 2. Similarly UI related code is not covered, the reader should be familiar with coding with common controls such as buttons, text boxes and list controls. FSTransactional Interface 22

23 FourthShift.TransactionClient Developer Guide If the FSTM module is installed, the source code can be found in the directory, \mfgsys\fstm\sdk Sample Code off the root of the Fourth Shift installation. A screen shot of the sample program is shown below. The UI steps the user through the steps of using the FSTIClient, first enabling the Initialize button, then if Logon is needed, the Logon button, and then finally the Submit Item button, displaying the FSTI Result in the large list control at the bottom. The first time the program is run, the output in the list box will be a copy of the string written into the archive file: Success: "ITMB00","AAA","11/06/2003","013:52:03","0","A","ITEM0","NEW ITEM 0","EA","","M","N","A","N","N","3","N","PLR","BYR","N",0,0,0,1,1,0,0,0," ","","1","W",100,"0",0,"N","GATEWC",0,"","","C","","","","","","","","", "","","",,"",,"","","0","","","",""," ","","",0,"","","","",,,,,"",,"","","","","","","","","","" The second time it is run, Item0 already exists resulting in an error return result. The output is then a dump of the FSTIError object that is returned: FSTransactional Interface 23

24 FourthShift.TransactionClient Developer Guide Transaction Error: Transaction: ITMB00 Description: Item Already Exists On Item Master MessageFound: True MessageID: 2233 MessageSource: fsmessagestring Number: 4 Fields in Error: 1 Field[0]: 7 Field name: ItemNumber Referencing the Class Libraries To access the FourthShift.TransactionClient and FourthShift.Transaction libraries C# and VB.NET programmers need to add references to the assemblies: Program Files =>Fourth Shift =>Managed =>FourthShift.TransactionClient.dll Program Files=>Fourth Shift => Managed => FourthShift.Transactions.dll This is for programming purposes only, the project reference settings should be set to copy local false because the run-time dlls are already installed in the global assembly cache (GAC) as part of the Fourth Shift workstation install. VB6 coders need to add the following two references: Fourth Shift Transaction Client Library Fourth Shift Transaction Library Once the references are established, C# and VB.NET coders need to add the appropriate using or imports statement as shown below. Note that both class libraries use the same SoftBrands.FourthShift.Transaction namespace. [C#] using System; using System.Collections; using SoftBrands.FourthShift.Transaction; [VB.Net] Imports System Imports System.Collections Imports SoftBrands.FourthShift.Transaction FSTransactional Interface 24

25 FourthShift.TransactionClient Developer Guide Variable Declarations Since this program is a Windows form application the code is organized as responses to button clicks contained in a form named FSTIInsertItemSample. The only member variable that is shared by the class methods and event handlers is a reference to an instance of FSTIClient; the declaration is straightforward: [C#] private FSTIClient _fsticlient = null; [VB.Net] Dim _fsticlient As FSTIClient [VB6] Private fsticlient As fsticlient Note that this code is using a coding convention of a prefix of _ for member variables for the.net languages and uses Hungarian notation for referencing controls. VB6 does not allow variables to start with an underbar (_) so the example code drops it. Initialization Part 1 This is the code for the first event handler, when Initialize is clicked. The code creates a new FSTIClient object and calls its InitializeByConfigFile method passing in the configuration filename found in the textconfig textbox. [C#] private void btninitialize_click(object sender, system.eventargs e) { Try { _fsticlient = new FSTIClient(); // Call InitializeByConfigFile() // second parameter = true is to participate in unified logon // third parameter = false, no support for impersonation is needed _fsticlient.initializebyconfigfile( textconfig.text, true, false ); [VB.Net] FSTransactional Interface 25

26 FourthShift.TransactionClient Developer Guide Private Sub btninitialize_click(byval sender As System.Object, ByVal e As System.EventArgs) Handles btninitialize.click Try _fsticlient = New FSTIClient 'Call InitializeByConfigFile() 'second parameter = true is to participate in unified logon 'third parameter = false, no support for impersonation is needed _fsticlient.initializebyconfigfile(textconfig.text, True, False) [VB6] Private Sub btninitialize_click() On Error GoTo ErrorHandler Set fsticlient = New fsticlient 'Call InitializeByConfigFile() 'second parameter = true is to participate in unified logon 'third parameter = false, no support for impersonation is needed fsticlient.initializebyconfigfile textconfig.text, True, False This code wraps the creation and initialization inside a Try-Catch Block (VB6 uses an On Error GoTo) because if the Initialize call fails, it will thrown an FSTIApplicationException. The remainder of the code for the event handler including the catch code will be shown shortly. InitializeByConfigFile takes three arguments, the first is a full path to a Fourth Shift configuration file. The second parameter is whether this application participates in unified logon, meaning that if a Fourth Shift application has already been started on this client workstation, then this program will not require the user to perform a Logon and the application will be sharing the previously consumed Fourth Shift license. The third argument indicates whether this program uses impersonation. In this code sample it is passing in false gaining a slight performance advantage. Impersonation means that this program will be submitting transactions using user identities besides the one used to logon. For example, the application might logon as AAA, but will sometimes be submitting transactions using the user id BBB. If impersonation is not enabled, if the application submits a transaction using the user id BBB it will be remapped to AAA. Passing FSTransactional Interface 26

27 FourthShift.TransactionClient Developer Guide in true for the third parameter is not sufficient to enable impersonation, it also requeries that the Fourth Shift administrator has configured an access list on the server that identifies each user that the original Logon Id is allowed to impersonate. More information on impersonation is contained in Section 6, FSTI SDK administration. Although this code uses IntializeByConfigFile, there is an alternate initialize method, InitializedBySystemName with the signature: public virtual new void InitializeBySystemName ( String SystemName, String ServerName, Boolean UnifiedLogon, Boolean Impersonation, String Port ) The main difference between the two initialize functions is that the first version requires a drive mapping to access the configuration file, the second version does not. Instead it expects the application to pass in arguments specifying the SystemName, ServerName and TCP/IP port used to connect to the Fourth Shift server. This form is useful in situations such as a web page, where accessing a mapped drive for the configuration file is either not possible or desirable. Instead the web application might store the required arguments in a local database, the registry or a local file. The three parameters, SystemName, ServerName and Port correspond to the values SystemName, DBServerName and ClientRemotePort that can be found in the Fourth Shift configuration (fs.cfg) file. Initialization Part 2 This is the remainder of the of the Initialize_Click event handler code. After the InitializeByConfigFile call, the code calls the IsLogonRequired property provided that an exception was not thrown by the Initialize call. IsLogonRequired will always return true if UnifiedLogon is disabled by passing in false for Initalize s UnifiedLogon parameter, otherwise true or false is returned based on whether other Fourth Shift applications have been started on the client workstation. If the return value is true then the Logon button is enabled. If the return value is false then the logon is skipped, and the SubmitItem button is enabled. Note that the catch expression is for the type FSTIApplicationException, a derived type from the.net Framework s ApplicationException type used by the Fourth Shift Transaction libraries. [C#] if ( _fsticlient.islogonrequired ) { // Logon is required, enable the logon button btnlogon.enabled = true; btnlogon.focus(); } else { // Logon is not required (because of unified logon), // enable the SubmitItem button btnsubmititem.enabled = true; btnsubmititem.focus(); } // Disable the Initialize button FSTransactional Interface 27

28 FourthShift.TransactionClient Developer Guide btninitialize.enabled = false; } catch (FSTIApplicationException exception ) { MessageBox.Show(exception.Message, "FSTIApplication Exception" ); _fsticlient.terminate(); _fsticlient = null; } } [VB.Net] If (_fsticlient.islogonrequired) Then 'Logon is required, enable the logon button btnlogon.enabled = True btnlogon.focus() Else 'Logon is not required (because of unified logon), 'enable the SubmitItem button btnsubmititem.enabled = True btnsubmititem.focus() End If 'Disable the Initialize button btninitialize.enabled = False Catch Exception As FSTIApplicationException MessageBox.Show(Exception.Message, "FSTIApplication Exception") _fsticlient.terminate() _fsticlient = Nothing End Try End Sub [VB6] If (fsticlient.islogonrequired) Then 'Logon is required, enable the logon button btnlogon.enabled = True btnlogon.setfocus FSTransactional Interface 28

29 FourthShift.TransactionClient Developer Guide Else 'Logon is not required (because of unified logon), enable the SubmitItem button btnsubmititem.enabled = True btnsubmititem.setfocus End If 'Disable the Initialize button btninitialize.enabled = False Exit Sub ErrorHandler: MsgBox "Failed to initialize FSTI client",, "FSTI Initialization" fsticlient.terminate fsticlient = Null End Sub Logon The logon handler code is below. The FSTIClient.Logon method returns 0 or less on success, greater then 0 on failure (invalid user or password). The Logon method takes a third parameter for receiving warning messages from the Logon method, for example if the user s password is expiring soon. In this case, the code does not expose the message to the user and instead ignores it. Remember that this code should only execute provided that the IsLogonRequired call returned true. After a successful logon, this code disables the Logon button and enables the SubmitItem button. [C#] private void btnlogon_click(object sender, System.EventArgs e) { string message = null; // used to hold a return message // from the logon call int status; // return value from the logon call status = _fsticlient.logon( textuserid.text, textpassword.text, ref message ); if ( status > 0) { MessageBox.Show( "Invalid user id or password" ); FSTransactional Interface 29

30 FourthShift.TransactionClient Developer Guide } } else { btnlogon.enabled = false; btnsubmititem.enabled = true; btnsubmititem.focus(); } [VB.Net] Private Sub btnlogon_click(byval sender As System.Object, ByVal e As System.EventArgs) Handles btnlogon.click Dim message As String logon Dim status As Integer call 'used to hold a return message, from the 'receives the return value from the logon status = _fsticlient.logon(textuserid.text, textpassword.text, message) If (status > 0) Then MessageBox.Show("Invalid user id or password") Else btnlogon.enabled = False btnsubmititem.enabled = True btnsubmititem.focus() End If End Sub [VB6] Private Sub btnlogon_click() Dim message As String logon Dim status As Integer call 'used to hold a return message, from the 'receives the return value from the logon FSTransactional Interface 30

31 FourthShift.TransactionClient Developer Guide status = fsticlient.logon(textuserid.text, textpassword.text, message) If (status > 0) Then MsgBox "Invalid user id or password",, "FSTI Logon" Else btnlogon.enabled = False btnsubmititem.enabled = True btnsubmititem.setfocus End If End Sub SubmitItem Handler The SubmitItem handler code contains the code that does the actual transaction processing. The SubmitItem handler code creates an ITMB00 object named myitem, sets it ItemNumber and ItemDescription properties based on the text boxes on the form and then submits myitem for processing using the FSTIClient.ProcessId method. ProcessId returns true if the transaction is processed successfully, false if there is a problem. If the transaction is successful and is an RCVR type transaction (as opposed to an SOP import transaction), then the return information received back from the call is a copy of the archive record written into the archive file. It is retrieved using the FSTIClient.CDFResponse property. Applications can parse this return record to determine system defined values such as the assigned line number when adding an order line. SOP transactions retrieve response information using FSTIClient.XMLResponse instead of CDFResponse. SOP does not generate archive records, hence the difference in the formats. If there is a problem performing the transaction (the ProcessId call returns false) then the handler uses a private method, DumpErrorObject, to display the error information. Note that the property FSTIClient.TransactionError returns an object of type FSTIError and the DumpErrorObject method is designed to display all the properties of the FSTIError object. [C#] private void btnsubmititem_click(object sender, System.EventArgs e) { ITMB00 myitem = new ITMB00(); myitem.itemnumber.value = textitemnumber.text; myitem.itemdescription.value = textitemdescription.text; // Clear previous results listresult.items.clear(); // Submit transaction for processing FSTransactional Interface 31

32 FourthShift.TransactionClient Developer Guide } if ( _fsticlient.processid( myitem, null )) { // success, get the response and display it using a list box listresult.items.add("success:"); listresult.items.add(""); listresult.items.add( _fsticlient.cdfresponse ); } else { // failure, retrieve the error object // and then dump the information in the list box FSTIError itemerror = _fsticlient.transactionerror; DumpErrorObject( myitem, itemerror ); } [VB.Net] Private Sub btnsubmititem_click(byval sender As System.Object, ByVal e As System.EventArgs) Handles btnsubmititem.click Dim myitem As New ITMB00 myitem.itemnumber.value = textitemnumber.text myitem.itemdescription.value = textitemdescription.text 'Clear previous results listresult.items.clear() 'Submit transaction for processing If (_fsticlient.processid(myitem, Nothing)) Then 'success, get the response and display it using a list box listresult.items.add("success:") listresult.items.add("") listresult.items.add(_fsticlient.cdfresponse) Else 'failure, retrieve the error object 'and then dump the information in the list box FSTransactional Interface 32

33 FourthShift.TransactionClient Developer Guide Dim itemerror As FSTIError = _fsticlient.transactionerror() DumpErrorObject(myItem, itemerror) End If End Sub [VB6] Private Sub btnsubmititem_click() Dim myitem As New ITMB00 myitem.itemnumber.value = textitemnumber.text myitem.itemdescription.value = textitemdescription.text 'Clear previous results ListResult.Clear 'Submit transaction for processing If (fsticlient.processid(myitem, Empty)) Then 'success, get the response and display it using a list box ListResult.AddItem ("Success:") ListResult.AddItem ("") ListResult.AddItem (fsticlient.cdfresponse) Else 'failure, retrieve the error object 'and then dump the information in the list box Dim itemerror As FSTIError Set itemerror = fsticlient.transactionerror DumpErrorObject myitem, itemerror End If End Sub The code above used the ProcessId method to process the transaction. FSTClient also has a ProcessCDF method that is used for submitting transactions as standard RCVR strings or SOP import strings. This method is most useful for incorporating into existing programs that are already forming CDF strings. Thus the code above could be rewritten using ProcessCDF as shown below: [C#] String itmb00string = myitem.getstring(transactionstringformat.fscdf); FSTransactional Interface 33

34 FourthShift.TransactionClient Developer Guide // itmb00string contains ITMB00,, 11/03/ 20003, 021:28:26, 0,, Item0, // New Item 0,,,. // Submit transaction for processing using ProcessCDF if ( _fsticlient.processcdf( itmb00string, null )) { [VB.Net] Dim itmb00string as String Itmb00String = myitem.getstring(transactionstringformat.fscdf) itmb00string contains ITMB00,, 11/03/ 20003, 021:28:26, 0,, Item0, New Item 0,,,. Submit transaction for processing using ProcessCDF if _fsticlient.processcdf( itmb00string, Nothing ) then. [VB6] Dim itmb00string As String itmb00string = myitem.getstring(transactionstringformat_fscdf) ' itmb00string contains "ITMB00","","11/03/ 20003","021:28:26","0","","Item0", ' "New Item 0","","",. ' Submit transaction for processing using ProcessCDF If fsticlient.processcdf(itmb00string, Empty) Then DumpErrorObject The DumpErrorObject method shows all the properties of the FSTIError class. This code demonstrates retrieving the properties from the FSTIError object. The method is written to generically accept as its first parameter any Fourth Shift Transaction object and an FSTIError object. The properties of the FSTIError object are: FSTransactional Interface 34

35 FourthShift.TransactionClient Developer Guide Description MessageID MessageSource MessageFound Number NumberOfFieldsInError GetFieldNumber(integer) contains the text that would normally be displayed in red in the status bar of the screen in Fourth Shift or the error message box that is displayed by SOP. can be used to write programs that can support multiple languages without changing the application source code. Since Fourth Shift is translated into many different languages, it can be difficult to write an application that react appropriately to return strings such as Database in Use, because the string returned will be different in each language. FSTI has a heuristic algorithm that attempts to reverse map error string from different languages into a common error number that will be the same regardless of the text. If the reverse mapping is successful then single source code can be written that supports all languages. This property must be combined with the MessageSource property for a unique identification number. indicates the source database of the error message when it is reverse mapped. There are two possibilities, 0 = Message String Database, 1 = Message Report Database. This value along with the MessageID value uniquely identifies the error. a Boolean that returns true if the heuristic algorithm reverse mapping the code into a common value for all languages is successful. Otherwise, it returns false. indicates the message number associated with the error. For SOP transactions, this value is used instead of the values MessageID and MessageSource to uniquely identify an error for all languages. In some cases, this will also be true for RCVR transactions. on an error, a transaction can have one or more fields that are incorrect. This identifies the number of fields that have been identified as being in error. the array of fields that have errors. The fields are identified by their positions in the CDF format of the transaction, starting with the field 1, the transaction name. [C#] private void DumpErrorObject( ITransaction transaction, FSTIError fstierrorobject ) { listresult.items.add("transaction Error:"); listresult.items.add(""); listresult.items.add( String.Format( "Transaction: {0}", transaction.name )); listresult.items.add( String.Format( "Description: {0}, fstierrorobject.description )); listresult.items.add( String.Format( "MessageFound: {0} ", FSTransactional Interface 35

36 FourthShift.TransactionClient Developer Guide fstierrorobject.messagefound )); listresult.items.add( String.Format( "MessageID: {0} ", fstierrorobject.messageid )); listresult.items.add( String.Format( "MessageSource: {0} ", fstierrorobject.messagesource )); listresult.items.add( String.Format( "Number: {0} ", fstierrorobject.number )); listresult.items.add( String.Format( "Fields in Error: {0} ", fstierrorobject.numberoffieldsinerror )); for ( int i = 0; i < fstierrorobject.numberoffieldsinerror; i++ ) { int field = fstierrorobject.getfieldnumber(i); listresult.items.add( String.Format("Field[{0}]: {1}", i, field )); ITransactionField myfield = transaction.get_field(field); listresult.items.add( String.Format( "Field name: {0}", myfield.name )); } } [VB.Net] Private Sub DumpErrorObject(ByVal transaction As ITransaction, ByVal fstierrorobject As FSTIError) listresult.items.add("transaction Error:") listresult.items.add("") listresult.items.add(string.format("transaction: {0}", transaction.name)) listresult.items.add(string.format("description: {0}", fstierrorobject.description)) listresult.items.add(string.format("messagefound: {0} ", fstierrorobject.messagefound)) listresult.items.add(string.format("messageid: {0} ", fstierrorobject.messageid)) listresult.items.add(string.format("messagesource: {0} ", fstierrorobject.messagesource)) listresult.items.add(string.format("number: {0} ", fstierrorobject.number)) FSTransactional Interface 36

37 FourthShift.TransactionClient Developer Guide listresult.items.add(string.format("fields in Error: {0} ", fstierrorobject.numberoffieldsinerror)) Dim i As Integer For i = 0 To i >= fstierrorobject.numberoffieldsinerror Dim field As Integer = fstierrorobject.getfieldnumber(i) listresult.items.add(string.format("field[{0}]: {1}", i, field)) Dim myfield As ITransactionField = transaction.field(field) listresult.items.add(string.format("field name: {0}", myfield.name)) Next i End Sub [VB6] Private Sub DumpErrorObject(ByVal transaction As ITransaction, ByVal fstierrorobject As FSTIError) ListResult.AddItem ("Transaction Error:") ListResult.AddItem ("") ListResult.AddItem ("Transaction: " + Format(transaction.Name, "%s")) ListResult.AddItem ("Description: " + Format(fstiErrorObject.Description, "%s")) If fstierrorobject.messagefound = True Then ListResult.AddItem ("MessageFound: True") Else ListResult.AddItem ("MessageFound: False") End If ListResult.AddItem ("MessageID: " + Format(fstiErrorObject.MessageID, "#0")) If fstierrorobject.messagesource = MessageSource_fsMessageString Then ListResult.AddItem ("MessageSource: fsmessagestring") Else ListResult.AddItem ("MessageSource: fsreportstring") End If ListResult.AddItem ("Number: " + Format(fstiErrorObject.Number, "#0")) ListResult.AddItem ("Fields in Error: " + FSTransactional Interface 37

38 FourthShift.TransactionClient Developer Guide Format(fstiErrorObject.NumberOfFieldsInError, "#")) Dim i As Integer For i = 0 To i >= fstierrorobject.numberoffieldsinerror Dim field As Integer field = fstierrorobject.getfieldnumber(i) ListResult.AddItem ("Field[" + Format(i, "#0") + "]: " + Format(field, "#0")) Dim myfield As ITransactionField Set myfield = transaction.field(field) ListResult.AddItem ("Field name: " + myfield.name) Next i End Sub Calling Terminate The FSTIClient Terminate method should be called when the application finishes to release system resources and guarantee a clean shutdown. The sample application uses the form s close handler to call terminate: [C#] private void FSTIInsertItemSample_Closing(object sender, System.ComponentModel.CancelEventArgs e) { if ( _fsticlient!= null ) { _fsticlient.terminate(); _fsticlient = null; } } [VB.Net] Private Sub FSTIInsertItemSample_Closing(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Closed If Not (_fsticlient Is Nothing) Then _fsticlient.terminate() _fsticlient = Nothing FSTransactional Interface 38

39 FourthShift.TransactionClient Developer Guide End If End Sub [VB6] Private Sub Form_Unload(Cancel As Integer) If Not fsticlient Is Nothing Then fsticlient.terminate Set fsticlient = Nothing End If End Sub FSTransactional Interface 39

40 FourthShift.Transactions API FourthShift.Transactions API The classes contained in the FourthShift.Transactions class library are based on the Fourth Shift Data Import Dictionary and SOP Import documentation. Programmers can use the FourthShift.Transactions classes to submit transaction processing requests to an FSTIClient object or to generate accurate comma delimited format (CDF) used by RCVR or SOP import. The classes are implemented using the.net Framework and support C#, VB.Net and Visual Basic 6.0. The Fourth Shift client install places the class library into the Global Assembly Cache (GAC), and also puts a copy for.net project reference purposes into the directory: program files/fourth shift/managed The namespace for the classes contained in the library is: SoftBrands.FourthShift.Transaction There are over 700 classes in the class library, each one named for its corresponding 6 letter RCVR or SOP import string. To give a sense of the extensiveness of the class library, below are the list of classes in the library that start with the letter A: APCA01, APCF00, APCV00, APCV10, APCV12, APCV19, APDS00, APDS01, APDS02, APDS03, APDS04, APDS05, APDS06, APDS07, APDS10, APDS12, APDS19, APEX02, APEX03, APID00, APID01, APID02, APID03, APID04, APID05, APID09, APID10, APID12, APID19, APID20, APID22, APID32, APIE00, APIE01, APIE02, APIE03, APIE09, APIE10, APIE12, APIE19, APIE20, APIE22, APIE32, APPA00, APPA01, APPA10, APPA12, APPA19, APPA20, APPA22, APPA32, APPD00, APPD01, APPD02, APPD03, APPD04, APPD05, APPD06, APPD07, APPD10, APPD12, APPD19, APRC01, APRQ00, APRQ01, APRQ02, APRQ12, APRQ19, APTX19, APTX20, APTX22, APTX32, ARAD01, ARCD00, ARCD01, ARCD02, ARCD03, ARCD04, ARCD05, ARCD07, ARCD08, ARCD10, ARCD12, ARCD19, ARCF01, ARCF02, ARCR01, ARCR01, ARCR02, ARCR10, ARCR12, ARCR19, ARPD00, ARPD01, ARPD02, ARPD03, ARPD04, ARPD05, ARPD07, ARPD08, ARPD10, ARPD12, ARPD19, ARSR01. Use the Visual Studio.Net object browser or VB6 object browser to view the entire list of classes. All of the 6 letter transaction classes derive from a common class, TransactionId that implements an interface ITransaction. This means all the classes share a subset of common properties and methods, those defined by the ITransaction interface, which will be described shortly. A CDF transaction string is composed of a set of fields separated by commas. The Import documentation indicates the fields that can be filled in and the fields that should be left blank. The FSTI Object SDK uses the term eligible to refer to fields that can, but do not have to be filled in. A subset of the eligible fields are the required fields, those fields that must be filled or else the transaction is guaranteed to be rejected. Each transaction class has a set of properties that are specific to that object, each one corresponding to one of the eligible fields in the original comma delimited format transaction string. As an example the first class, APCA01, has the following properties that are based on its eligible fields: BankId PaymentDate PaymentForm PaymentReferenceNumberNew PaymentReferenceNumberOld Reassignment FSTransactional Interface 40

41 FourthShift.Transactions API Similar to the transaction class itself, each of these properties derives from a common class, TransactionField that implements the interface ITransactionField. This interface will also be described shortly. In summary, the FourthShift.Transactions class library consists of a large number of transaction classes, each corresponding to a 6 letter CDF transaction string found in the Import documentation. Each of the transaction classes supports the ITransaction interface. Each transaction class also has a set of properties defined by its eligible fields. These eligible fields are all TransactionField objects that implement the ITransactionField interface. Besides the 700+ transaction classes, there is another important class, TransactionFactory contained in the library. The TransactionFactory has a method CreateTransactionFromCDF that reverse maps CDF transaction strings into the correct responding transaction object. Details on the TransactionFactory class are later in this section. The class library uses the class TransactionFieldException when throwing an exception, for example if there is an attempt to set a property to too long a value. It is derived from the.net frameworks ApplicationException class and adds no new properties or methods. By introducing a new type, programmers can write try-catch blocks that are hierarchical, first catching TransactionFieldException, then ApplicationException, then SystemException and finally generic exceptions. ITransaction Interface This is the interface that all transaction classes implement. ITransaction Public Properties Name Type Description Category TransactionCategory (read only) An enumerated type that identifies the Fourth Shift application that handles this type of transaction. Valid responses are: fscore = 1 fssopm = 2 fsengm = 3 The first response indicates that it is an RCVR type transaction, the second is that it is SOP import transaction, the third that it is an ENGM transaction (possible future use). Description String (read only) A one line description of the behavior of the transaction. Name string (read only) The 6 letter name of the transaction object. RequiredAreSet bool (read only) Returns true if all the required properties have been set to some value, false if some of them have not been set. There are some fields that under certain situations are required, for example if an item is lot traced. Fields of those type (may be required) are not included in the RequiredAreSet, thus false positives are possible in some circumstances. ITransaction Public Methods FSTransactional Interface 41

42 FourthShift.Transactions API Name Type Description C#: get_field(name) VB.Net: Field(Name) C#: get_field( Number) VB.Net: Field(Number) GetEligibleField Numbers GetRequiredField Names GetRequiredField Numbers GetString(Format) C#: ItransactionField(String) VB.Net: ItransactionField(String) C# ItransactionField(Int32) VB.Net ItransactionField(Int32) C#: int [] VB.Net Integer() C#: string[] VB.Net: String() C#: int[] VB.Net: Integer() string TransactionStringFormat Name (argument 1) should specify the name of an eligible field. The return from the method is a reference to the ITransactionField object with the passed in name. If the name is not a valid property of the object, null or nothing is returned. Number (argument 1) should specify the position of an eligible field in the CDF string corresponding to this transaction object. The return from the method is a reference to the ITransactionField object at that position. If the number is not an eligible position, null or nothing is returned. Returns an array of integers that describe the eligible positions in the CDF string that corresponds to this transaction object. Returns an array of names that are the names of the properties that must be filled for this to be a valid transaction. Returns an array of integers that are the positions that must be filled for the corresponding CDF transaction string to be a valid transaction. TransactionStringFormat (argument 1) should be either fscdf or fsxml, specifying the format of the string that is returned (CDF or XML). The method returns a string that is the properly formatted version of the transaction string for this type of transaction object based on the current settings of its eligible field properties. The date and time fields are filled in with the current date and time. ITransactionField Interface Each transaction class has a set of eligible fields, that when accessed, return a reference to an ITransactionField interface. Accessing each of the properties of the ITransactionField interface requires first specifying the property name. For example to set the APCA01 objects BankId to a value the following syntax is required: APCA01.BankId.Value = some value Notice that Value is property of BankId, which is a property of APCA01. ITransactionField Public Properties Name Type Description FSTransactional Interface 42

43 FourthShift.Transactions API Behavior TransactionFieldBehavior (read only) For future use, indicates if a field is generated by the system such as an order line numbers (fsgenerated), is a fixed value (fsstatic) or is a normal read/write property. Currently always returns fsnobehavior. IsRequired bool (read only) True indicates that this is a member of the set of required fields for this transaction class. False indicates it is not always a required field although it might be under certain circumstances (for example if lot tracing or multi-currency is enabled). Length int32 (read only) Maximum length accepted for this field when setting the Value property. Name string (read only) The name of the property. This allows the ITransaction- Field interface to be used generically, and applications can discover the name of the field at run-time. Number int32 (read only) The field position of this property when generating its comma-delimited format string. Type TransactionField- Type (read only) An enumeration that identifies the type of the property (alphanumeric, date, number). Valid returns are: fsalpha = 1 fsdate = 2 fsnumeric = 3 Value string The actual value that will be written into the field at position Number if the comma-delimited format string is generated. Note that this property can be set as well as retrieved (it is the only read/write property). TransactionFactory Class The TransactionFactory class is used for taking CDF strings (or in the future XML formatted strings), and returning back the Transaction object that corresponds to the string. The class eliminates the need to write programs that parse archive file records and can also be used to parse the TransactionClient s CDFResponse property turning it into an easy to use Transaction object. TransactionFactory Public Methods Name Type Description CreateTransaction- FromCDF (TransactionCDF) CreateTransaction- FromXML (TransactionXML) Itransaction(string) Itransaction(string) TransactionCDF should be a Fourth Shift RCVR or SOPM transaction string. The return from this function is a reference to the ITransaction interface of a newly created Transaction class based on the 6 letter code in the first field of the passed in string. It returns null or nothing if there is a problem parsing the string. For future use, same as above but instead of a string in comma-delimited format, it accepts a string using an XML schema that has yet to be specified. FSTransactional Interface 43

44 FourthShift.TransactionClient API FourthShift.TransactionClient API The FourthShift.TransactionClient class library contains the classes used for submitting transaction requests to Fourth Shift and receiving back real-time responses. It is implemented using the.net Framework and supports C#, VB.Net and Visual Basic 6.0. The Fourth Shift client install places the class library into the Global Assembly Cache (GAC), and also puts a copy for.net project reference purposes into the directory: program files/fourth shift/managed Although the files are always installed, a run-time failure will occur if the FSTM module is not properly licensed from Fourth Shift. The namespace for the classes contained in the library is: SoftBrands.FourthShift.Transaction Classes contained in the class library are: FSTIClient FSTIError FSTIApplicationException FSTIXMLArchive (do not use intended for future use) FSTIXMLError (do not use intended for future release) There are two enumerated types: MessageSource TransactionStatus The remainder of this section are the detailed description of the classes and types in the library. For some properties and methods, programmers needs to be aware of whether the transaction submitted is an RCVR transaction or an SOP import transaction. Information that is specific to a specific transaction type is indicated with an (RCVR) or (SOP) to indicate that the method or property applies only for that type. FSTIClient FSTICLient is the class used for submitting transactions for processing. FSTIClient Public Properties Name Type Description CDFResponse string (read only) The comma delimited string returned after a successful process call (RCVR). This is a copy of the record writing into the archive file. Some transactions write more then one record into the archive file. In those cases, the record returned is the first record written, and the second and later records are not available as return values. FSTransactional Interface 44

45 FourthShift.TransactionClient API IsLogonRequired bool (read only) A property that indicates if a logon is needed. The property should be examined after FSTIClient has been initialized to determine if the logon method needs to be called. If IsLogonRequired is true and a logon is skipped all future calls will fail until a successful logon is performed. ServerName string (read only) The name of the Fourth Shift server that the FSTIClient is connected to. Status TransactionStatus (read only) (Future use) The TransactionStatus of the FSTI engine fsunknown = -1 fssupportedandenabled = 0 fsnotsupported = 1 fssupportedanddisabled = 2 See discussion in section FSTIClient Transaction Bracketing. TransactionError FSTIError (read only) Valid only after an FSTIClient process method returns false. The FSTIError object returned contains the detailed error information. UserId string (read only) The name of the user that is logged on. This is particularly useful if Unified Logon succeeds to determine the user id. Users string[] (read only) An array of strings listing the UserIds that the logged on user may impersonate. XMLResponse string (read only) An XML formatted string returned after a success process call (SOP). See section SOP Response Format for a description of the XML responses generated by SOP transactions. FSTIClient Public Methods Name Type Description BeginTransaction void (Future use) Starts a transaction bracket. See section FSTIClient Transaction Bracketing. CancelTransaction void (Future use) Cancels/Rollbacks a transaction bracket. See section FSTIClient Transaction Bracketing. CommitTransaction void (Future use) Commits a transaction bracket. See the discussion found in section FSTIClient Transaction Bracketing. FSTransactional Interface 45

46 FourthShift.TransactionClient API InitializeByConfigFile (ConfigurationFile UnifiedLogon Impersonation) InitializeBySystemName (SystemName ServerName UnifiedLogon Impersonation Port ) Logon (UserId Password Message ) void string bool bool void string string bool bool string int string string string Initializes an FSTIServer object by passing in a full path to a Fourth Shift configuration file (first argument). This method should be called before any other methods or properties. If UnifiedLogon (second argument) is true, then it detects if a prior Fourth Shift application has been started on the client workstation and if so uses that applications UserId automatically. If the FSTI application is the first application started on the workstation then later applications will use the FSTI application s user id. If Impersonation (third argument) is true, then the application may pass in UserIds other then the original logon name when submitting transactions and the transaction will attempt to execute as if it were the alternate user. If this argument was set to false and the application tries to impersonate a different user, the request will be remapped back to the original user id. Throws an FSTIApplicationException if the initialization fails. Initializes an FSTIServer object by explicitly passing in the Fourth Shift System Name, Server Name and Port (default is 7361). (First, second and fifth arguments). Use this call to avoid requiring a mapped drive to the location of the Fourth Shift configuration file. This method should be called before any other methods or properties. See above for a description of UnifiedLogon and Impersonation arguments. Throws an FSTIApplicationException if the initialization fails. Checks that the passed in user id and password (first and second arguments) are a valid Fourth Shift UserId and password. A successful logon returns a number less than or equal to 0. A return value of greater then 0 indicates an invalid user id or password. A successful logon can return an optional message (the third argument to the method). Typically this message is the number of days left till the users password is going to expire if password expiration is turned on. Applications can choose whether to display this message or ignore it. There may be additional messages in future Fourth Shift releases. Logon should only be called provided the IsLogonRequired property is true. A successful call to this method consumes a Fourth Shift license unless unified logon is enabled and a previous logon from the workstation is detected. The userid and password are encrypted prior to sending across process boundaries. FSTransactional Interface 46

47 FourthShift.TransactionClient API ProcessCDF (TransactionCDF UserId ) ProcessId (TransactionId UserId ) ProcessXML (TransactionXML UserId ) SetToRunUnlicensed (key ) bool string string bool ITransaction string bool string string bool int32 TransactionCDF (first argument) should be a string in comma-delimited format, either a valid RCVR string or a valid SOP import string. The string is sent to the Fourth Shift server for processing. ProcessCDF returns true if the transaction is processed successfully, false if there is a problem. UserId (second argument) is used to impersonate a user id other then the original user id provided when logging on. The parameter is optional in VB.Net, required in C# (pass in null for the same effect). The argument is only examined if the Initialize method enabled impersonation by passing in true, otherwise it is ignored. TransactionId (first argument) should be an object that implements the SoftBrands.FourthShift.Transaction.ITransaction interface. Generally, this will be an object coming from the FourthShift.Transactions class library. The transaction request that the ITransaction argument represents is sent to the server for processing. ProcessID returns true if the transaction is processed successfully, false if there is a problem. See ProcessCDF description above for details on using the UserId argument. Not currently supported, will provide for a third process request format, as an XML string. Current formats that are supported are comma delimited (see ProcessCDF) and passing in a transaction object (see ProcessID). (SoftBrands Manufacturing use only). This method allows SoftBrands Manufacturing to develop applications that use FSTM without requiring a site having to purchase the FSTM module. An example of this is real-time Shopfloor. SetToRunUnlicensed returns true if the passed in key is valid, false otherwise. This function should be called immediately after Initialize. Terminate void Releases the resources that the FSTIClient object is using, including disconnected the client from the server. The FSTIClient object can no longer be used after this has been called. It is important to call this method as part of a proper shutdown to make sure all critical resources are released. SOP Response Format SOP transactions return a string in XML format when a transaction executes successfully. This string contains useful return information, particularly system generated return values. The string uses the XML FSTransactional Interface 47

48 FourthShift.TransactionClient API format shown below allowing applications to use standard XML parsers to retrieve the return values of interest. <SOPTIRESPONSE TRANSACTION= SOaaxx (always returned, SOPCxx, SOPOxx or SOCIxx) ATTRIBUTE2= xxxx (always returned, CUSTOMER for SOPCxx and SOCIxx, ORDER for SOPOxx) ATTRIBUTE3= xxxx (sometimes returned, will be DELIVERYLOCATION or CUSTOMERITEM or LINE) PRICEADJUSTMENTSEQUENCE= xxx (sometimes returned) /> The following tables summarize the XML attributes returned for each of the transactions Attribute2 Transaction CUSTOMER= CustomerID ORDER= OrderNumber SOPCxx, SOCIxx SOPOxx Attribute3 Transaction DELIVERYLOCATION= DeliveryLocation CUSTOMERITEM= Customer Item ID LINE= Order Line Number SOPC06-08 SOCI00, SOCI01, SOCI10 SOPO04-06, SOPO09-10, SOPO14-16 PRICEADJUSTMENTSEQUENCE Transaction PRICEADJUSTMENTSEQUENCE= Order Header Price Adjustment Seq # PRICEADJUSTMENTSEQUNECE= Line Level Price Adjustment Seq # SOPO11-13 SOPO14-16 FSTIError Class The FSTIClient property TransactionError returns an object of type FSTIError when a transaction processing error occurs. Depending on the type of error, not all properties of the returned FSTIError object are valid. An important concept for RCVR transactions is that there is an attempt to reverse map error description strings into an error value that is identical regardless of the underlying language of the Fourth Shift system. This means that an error message such as Database in Use will return the same MessageId and FSTransactional Interface 48

49 FourthShift.TransactionClient API MessageSource values even though the Description string will change from language to language. The algorithm for reverse mapping strings is heuristic based and can fail. When it fails, the MessageFound property will be set to False, when it succeeds, MessageFound will be True. An FSTI application can examine the Description field to detect and react to particular error messages such as Database in Use, but an application written this way will not work properly when the installed Fourth Shift system is in a different language. Using the MessageFound, MessageID and MessageSource properties, the same application can be written only once and it will support all Fourth Shift languages. SOP import transaction that fail also return a MessageID, but that value is not based on a reverse mapping, so the MessageFound property is not used. The MessageID property is always set. A second important concept is that of field positions. Each transaction ultimately corresponds to a transaction string, and each element in that string has a position, starting with the first element, at position 1, that identifies the transaction (for example, the string COMT00, MOMT00, SOPC00 ). When an error is detected, it may be because one or more of the fields in the string are invalid, for example an item does not exist, or a date is too early. RCVR transaction failure information supports identifying the fields that are in error using the property NumberOfFieldsInError and method GetFieldNumber. This feature is particularly useful in writing applications that highlight multiple fields that are incorrect as many web forms do, instead of having to fix errors one at a time and then trying again. FSTIClient Public Properties Name Type Description Description string (read only) The text of the error message that would appear in the status bar for an RCVR type transaction or in a message box for an SOP transaction. MessageFound bool (read only) RCVR style transactions attempt to have their description test reversed mapped to a unique message id that is language independent. If the reverse mapping is successful then this property is set to true, else it is false. (RCVR) MessageID int32 (read only) When a reverse mapping is successful, this property contains the unique error message corresponding to the description text. (RCVR) This property is always valid for SOP transactions (SOP). MessageSource MessageSource Reverse mapping of description strings can come from two sources, MessageStrings or ReportStrings. This property identifies the source. It should be combined with the MessageID to uniquely identify an error message. (RCVR) Valid returns: fsmessagestring = 0 fsreportstring = 1 Number FSTIError (read only) In places in the Fourth Shift where the Description text is locating by reading it from a message file, this is the numeric identifier used to look up the error from the message file. (RCVR) FSTransactional Interface 49

50 FourthShift.TransactionClient API NumberOfFieldsInError int32 As per the name, indicates the number of positions that are identified as being incorrect in the transaction string corresponding to the requested transaction. Use with the GetFieldNumber method to identify the actual fields in error. (RCVR) Source String Contains the name of the origin of the error (GUI, Application, Database, etc.). (RCVR) FSTIClient Public Methods Name Type Description GetFieldNumber( index ) int int If the property, NumberOfFieldsInError is set, then GetFieldNumber is used to retrieve the position in the transactions corresponding transaction string for each field that is in error. Valid values for the index are 0 to NumberOfFieldsIn- Error 1. FSTIClient Enumerated Types Name MessageSource TransactionStatus Description When the FSTIError property MessageFound is true, then the Message- Source property will be one of the two following values: fsmessagestring = 0 fsreportstring = 1 This combined with the FSTIError property MessageId uniquely identifies the error returned independent of the language of the installed system. Intended for future use, this enumerated type indicates the state of the transaction bracketing support of the installed Fourth Shift system. fsunknown = -1 fssupportedandenabled = 0 fsnotsupported = 1 fssupportedanddisabled = 2 See the description in section FSTIClient Transaction Bracketing. FSTIClient Transaction Bracketing A future release of the FSTI Object SDK may support the ability to submit multiple transactions treating them as one larger transaction that can be committed or rolled back atomically. In such an environment, applications could create an order header, start adding order lines, detect a problem and back out all the lines including the header. The FSTIClient property, Status is used to interrogate the level of transaction support provided by the current Fourth Shift system. Valid return values are: FSUnknown FSTIClient is unable to determine the transaction support. FSTransactional Interface 50

51 FourthShift.TransactionClient API FSSupportedAndEnabled FSNotSupported FSSupportedAndDisabled Transaction bracketing is working. This Fourth Shift System does not support transaction bracketing. This system is capable of providing transaction bracketing, but it is not enabled. FSTIApplicationException Class The FSTIApplicationException class is used by classes contained in the SoftBrands.FourthShift.Transaction namespace when throwing an exception. It is derived from the.net frameworks ApplicationException class, adding no new properties or methods. It is used by the FSTI Object SDK classes so that programmers can write try-catch blocks that are hierarchical, first catching FSTIApplicationExceptions, then ApplicationExceptions, then SystemExceptions and finally generic exceptions. FSTransactional Interface 51

52 FSTI System Administration FSTI System Administration FSTI has two important administrative concepts, the Fourth Shift Remoting Service, a.net Window Service running on the Fourth Shift server and the FSSDKAdmin Console, a Microsoft Manage Console Snap-In used for configuring impersonation. The next section uses an example of a theoretical Fourth Shift FSTI environment to motivate a description of the purpose and interactions of the Fourth Shift Remoting Service with the other FSTI components. It is followed by a detailed description of using and configuring FSTI Impersonation. Fourth Shift Remoting Service The Fourth Shift environment shown in the diagram that follows is used to introduce the role that the Fourth Shift Remoting Service plays in the FSTI architecture. It assumes that there are two Fourth Shift Systems installed on the Fourth Shift server with system names Live and Test. On the left are six active FSTI client applications, such as Real-Time Shop Floor, Visibar or Visiwatch. FSTI supports multiple FSTI applications running simultaneously on the same workstation, so the six clients could be running on six or fewer separate workstations. The Fourth Shift FSTI server is shown on the right. For performance reasons, this is usually the same as the Fourth Shift database server, and any alternative configuration requires manual installation steps. The.Net Remoting interface used to connect to the FSTI Server is shown in the diagram as the dashed vertical line to the left of center of the diagram. Each FSTI application is connected to its own copy of FSGuiApp.exe running on the server. The creation of the FSGuiApp.exe is the responsibility of the Fourth Shift Remoting Service. When the FSTI application calls one of FSTIClients Initialize methods, a TCP/IP connection using.net remoting is established between the application and the Fourth Shift Remoting Service. The Fourth Shift Remoting Service loads a.net assembly named FourthShift.TransactionServer.dll. That assembly uses an out-of-proc COM call to start a dedicated copy of FSGuiApp.exe to handle requests for the new connection. Each FSTI application is connected through the Fourth Shift Remoting Service to its own copy of FSGuiApp.exe. FSTransactional Interface 52

53 FSTI System Administration If the FSTI Application makes an SOP transaction request, the FourthShift.TransactionServer assembly will create an out-of-proc copy of a process named SOPTIServer.exe to handle the SOP transactions. The Fourth Shift Remoting Service is started and stopped using the standard mechanisms used for interacting with all Windows Services. It can be found in the directory Program Files\Fourth Shift\Managed with the name FourthShift.RemotingService.exe. In that directory is an XML configuration file, FourthShift.RemotingService.exe.config, that includes the setting for the port used to communicate with the clients. If you change the default port, the entry: ClientRemotingPort = New Port Number must be added to the Fourth Shift configuration file so that the clients will contact the server using the correct port. Impersonation The FSTI application program interface requires that applications log into Fourth Shift using a valid Fourth Shift UserId. All transactions submitted by the application are then processed as that user. An implication of this is that a transaction submitted as a different UserId will be remapped to the original UserId unless impersonation is enabled. Impersonation provides the ability for an FSTI application to submit transactions using other Fourth Shift UserIds. For example, without impersonation, if an FSTI application logs in as user AAA and then tries to submit a request as user BBB, FSTI will change the transaction back from user BBB to AAA before trying to process the transaction. With impersonation enabled and appropriately configured, the transaction submitted by AAA can run as BBB. Note that when AAA impersonates BBB, the transaction runs with the security rights of BBB and not of AAA. Impersonation is only supported by RCVR transactions, SOP transactions do not support impersonation. The Fourth Shift SDK Administrator is in the Fourth Shift tools menu and is used to configure impersonators. The figure below is a screen shot of the tool in use: FSTransactional Interface 53

54 FSTI System Administration In the Figure, user VBS has been given permission to impersonate anyone (*) or users AAA and BBB. This is an unrealistic example, since it is unnecessary to add AAA and BBB if VBS is already given the right to impersonate everyone, but it is used here to demonstrate the two options, everyone or a set of specific users. To add an impersonator to a data source, keep expanding the nodes until reaching the Impersonators node, then right click the Impersonators node and select New from the drop-down menu and then select Impersonator. The impersonator is given a unique name that then needs to be renamed for example to VBS. To grant the impersonator permission to assume another user s identity, select the Impersonator (VBS), right click and select New from its drop-down menu and then select User. The user is given a unique name that is then easily renamed to * or AAA by right clicking and doing a rename. FSTransactional Interface 54