External Invocation

Basics

The application offers the option to initialize other software products. Single or fixed parameters, as well as values from e.g. the currently open mask can be forwarded to the invoked program.

We differentiate between several invocation types:

Type	Remark
EXCEL	Microsoft Excel invocation
EXCELTRANSFER	Bidirectional Excel integration
EXE	Invocation of an executable Windows EXE file
INI	.exe call with creation of an .ini file Only in the Windows Client
OUTLOOK	Microsoft Outlook invocation;
SAP	Invocation of functions and masks in SAP
SERIESACTION	Invocation of a serial letter from an entity Only in the Windows Client
URL	Invocation of a website via the system-configured standard browser
WEBSERVICE	Web service call Only in the Windows Client
WORD	Microsoft Word invocation

All invocations are logged in a separate table. You can access the invocation interface in the administration menu via the node External invocations. A search window opens, where you can search directly for a specific existing invocation or you close the search window and click the button New to create a new dataset.

Figure: Mask of an external invocation

• Name the new invocation in the field Title as it should later be displayed in the invocation menu.

• Enter a tooltip in the field Description to be displayed later as a mouseover for the relevant button. It will be displayed in the invocation menu and in the button bar.

• Select the entity for which the invocation should be available in the field Entity. The invocation will be displayed for all masks if this field remains empty (entry of an empty key), otherwise it will only appear for the selected mask. Please note that parameterized invocations are usually not suitable for all masks.

• Enter the type of invocation (see above) in the field Call type.

• Ad a script for the call configuration (see below) in the Memo field at the top right

• Select an icon (GIF or JPG) for the field Image that will be displayed for the invocation.

• The Command field is only accessible for the call type EXE. Here you enter the path and file name of the executable program.

• The Execute in field is only accessible for the call type EXE. Here you can optionally specify another working directory for the invoked program.

• Setting a check mark for the field Navigation bar allows you to specify, whether the call should also be available via the call bar or should only be displayed in the call menu.

• Optional parameters to be transferred to the program an be entered in the field 'Parameter'. The syntax depends on the invoked software.

• Toolbar and Button bar fields: External invocations that should neither be displayed in the toolbar nor in the quick start bar (both options deactivated) do not appear for the user in the application (only available in the mask script) and are therefore not offered in the proposal list (COMMAND).

The syntax for the transfer of parameters from within the application looks like this: ${Fieldname.Entityname}

The matching entries are looked up via the administration console in the section Customizing / Field attributes using a relevant column filter.

Grouping and sorting

The sequence in which buttons for external invocations are displayed in the drop-down menu can be influenced via the numerical field "Sort order". Please note when working on this field that the drop-down menu displays entity-specific, as well as entity-independent entries.

Figure: External invocation 'Excel' and effects for the pull-down menu

In addition to sorting entries (deciding the order in which they appear), you can also group invocations in submenus. You can specify possible groupings in the key field "Entry Grouping".

An existing grouping can be selected when processing an external invocation. This will then show the external call within that menu. The external call will appear at the top level if no grouping (empty key '?') is selected. Sorting within groupings is done just like ‘Sort order'.

The following sequence applies for the sorting of menus with all external invocations (top to bottom):

1. The groupings are initially displayed in alphabetically ascending order (A --> Z) of their internationalized names. Within each grouping, another sorting occurs in accordance with the value in the field Sort order.

2. After that follow the invocations without grouping. These are sorted according to the value in the field Sort order

This sorting applies notwithstanding whether an entry is entity-specific, i.e. all invocations available for the current window (general and entity-specific calls) are sorted according to the description above.

The external calls are also displayed in the button bar at the bottom left of the application (controlled by the administrator). This bar also complies with order and grouping. The buttons in the bar are added from left to right as described above. First are the groupings in ascending alphabetical order (A --> Z), within the grouping, sorting is done according to the Sort order. Then follow the invocations without grouping. A grouping is symbolized by a button with the relevant icon. Clicking the button will open a pop-up menu with all the entries of this grouping.

Internationalization

In external invocations, two rows are reserved for internationalization. The title and description are listed and marked in brackets.

Only the current external invocation will be displayed in the I18n dialog (i.e. exactly two rows without a browse option within the I18n dialog) if the button I18n

The field 'Description' was included in the system search, which means that changed system searches will have to be adjusted after the update.

Scripting in the Memo field

The Script (Memo field at the top right) works exactly like a mask script. Only accessing the mask field is different:

Instead of Fieldname.value you will have to write ${Fieldname.EntityNname}.

Example: Matchcode.value becomes ${Matchcode.Customer}

System variables can also be used for external invocations.

Example

%TEMP%\Dateiname.ini

is replaced by

C:\Temp\Dateiname.ini

These are replaced with the following fields at runtime:

• Memo field (Params.InvocationExt)

• Command (Executeable.InvocationExt)

• Execute in (WorkingDirectory.InvocationExt)

Type: EXCELTRANSFER

This invocation type opens an Excel template, which was saved in the system. The template is configured in the administration console under 'Template management'. The configuration of the external invocation must include the correct template name and the template entity.

The following fields are important:

• Call type (EXCELTRANSFER)

• Entity (must match the entity of the Excel template)

• Memo field (name of the Excel template)

Figure: Relationship between a saved Excel template and the configuration of the external invocation

Type: URL

Example call Map24

In the following example we will configure an invocation of the website Map24. A direct route from the company headquarters to the business partner location is to be calculated.

The invocation is done like this:

• Title: Map24

• Description: Route to the current dataset in Map24

• Entity: CUSTOMER (i.e. the current business partner)

• Call Type: URL

• Image: The Map24 icon

• Navigation bar: Yes

• Parameter field:

link2.map24.com/?lid=0f8488fc&maptype=JAVA&action=route&dstreet=
${Street.Customer}+${StreetNumber.Customer}&dzip=${ZIP.Customer}&dcity=${City.Customer}&dcountry=de&sstreet=
Friedrich-List-Strasse+31&szip=35398&scity=Giessen&scountry=de&sname=CURSOR+Software+AG&submit=+%3E%3E+

This is a mix of variable and fixed parameters, which is handed over to the Map24 portal.

Variable parameters are:

• ${Street.Customer} Street name of the business partner location

• ${StreetNumber.Customer} House number

• ${ZIP.Customer} ZIP code

• ${City.Customer} City

The start address for the route will in this case be CURSOR Software AG in Gießen, which is stated in the bottom part of the parameter block.

In order to access the above parameters, their names must first be looked up via the administration console. In the range Customizing / Field attributes you would set the column filter in the entity column to Business partner for our example and you would then only see the database fields of the business partner.

Set the column filter for the column Field to *Street* to see the name in the field. You will now only be displayed fields that contain the string Street. You will have two result entries: the storage location of the street of the person and the storage location of the street of the actual business partner.

The various column filters allow you to quickly identify the parameters that have to be forwarded.

Type: SERIESACTION

Configuring the invocation

An entity must be selected and a script must be stored.

After execution, the wizard for sending a serial letter or a serial mail will be invoked and pre-filled, depending on the configuration.

Script

The script always has the following basic structure:

 public void init()
{
}

The following configuration options exist for the wizard:

Specifying a custom name for the wizard (the default name will otherwise be shown)

//setTitle(String title)                   ab 14.1
config.setTitle("Umschläge und Etikettendruck");

Pre-filling the wizard using a template and specifying, whether the user will have the right to select a different one. This parameter must exist and must be pre-filled with a template with a valid name.

//config.setTemplate("NAME DES TEMPLATES", editierbar?)
config.setTemplate("SERIENBRIEF BLANKO (Beispiel)", true);

Specifying, whether the user will have the right to view and edit the search.

//config.editSearch(editierbar?)
config.editSearch(true);

Specifying, whether the user will have the right to view the search results and remove datasets as needed.

//config.displayResult(darfDerBenutzerDieErgebnisseSehen?)
config.displayResult(true);

Specifying, whether the user will have the right to add datasets by loading a file.

//config.addSearch(darfDerBenutzerSuchergebnisseHinzuFügen?)
config.addSearch(true);

Specifying, whether he user will have the right to save the search result.

//config.saveSearch(speichern?)
config.saveSearch(true);

Pre-filling the title of the document dataset and specifying, whether the user will have the right to modify it. Field content can be used.

//config.setSubject("Mein Text "+ MeinFeldInhalt.value , editierbar?)
config.setSubject("Mein Text "+ MatchCode.value , false);

Adding a file as a pre-filled attachment to the wizard.

//config.addFile("Mein voll qualifizierter Pfad")
config.addFile("C:\\Meinordner\\MeineDatei.txt");

Specifying, whether the user has the right to add files as attachments.

//config.changeFiles(editierbar?)
config.changeFiles(false);

Specifying the default setting of the 'Protocol activity' checkbox and whether the user has the right to change the value.

Note: The 'createLogActivity' method was renamed 'createProtocolActivity' as of version 14.1. The old method name will continue to be supported.

//config.createProtocolActivity(aktivieren?[, editierbar? ])   ab 14.1
config.createProtocolActivity(false);    // identisch zu config.createLogActivity(false) - bis 13.2
//oder
config.createProtocolActivity(false, true);  

Specifying the default setting of the 'Reminder activity' checkbox and whether the user has the right to change the value.

//config.createRemindingActivity(aktivieren?[, editierbar? (ab 14.1)])
config.createRemindingActivity(false);
//oder
config.createRemindingActivity(false, true);  // ab 14.1

Specifying the default setting of the 'Collector activity' checkbox and whether the user has the right to change the value.

//config.createSeparateActivities(aktivieren?[, editierbar? (ab 14.1)])
config.createSeparateActivities(true);
//oder
config.createSeparateActivities(true, true);  // ab 14.1

Specifying, whether the serial mail wizard or the serial letter wizard should be started.

//config.setType("Typ(LETTER oder MAIL)")
config.setType("LETTER");

If the type LETTER is selected: Specifying, how and in what format it should be created.

//config.setFormat("Option zum Wählen", editierbar?)
config.setFormat("Serialletter", true);
config.setFormat("Controlfile", true);
 
//config.setFormat("Option zum Wählen(Controlfile oder Serialletter)","Format(Excel oder CSV)", editierbar?)
config.setFormat("Controlfile","Excel", true);
config.setFormat("Controlfile","CSV", true);
config.setFormat("Serialletter", "Excel", true);
config.setFormat("Serialletter", "CSV", true);

If the type LETTER is selected: Specifying, whether the serial letter document should only be generated as a test.

//config.setTestMode(Test Modus?, editierbar?)
config.setTestMode(false, true);

If the type LETTER is selected: Specifying, whether the document dataset for the generated serial letter document should be opened.
Not to be confused with the serial letter document file.

//config.openWindowLevelForDocument(aktivieren?)    ab 14.1, Standard ist true
config.openWindowLevelForDocument(false);

If the type LETTER is selected: Specify, whether the generated serial letter document file should be opened. The default setting is for the document to open.

//config.openDocument(aktivieren?)             ab 14.1, Standard ist true
config.openDocument(false);

Presetting the protocol and reminder activity in the wizard

The protocol and reminder activity can basically be pre-configured in all document wizards via a PropertyMapping entry for each template type. The fields in the serial letter/serial mail wizard would therefore generally be pre-populated.
Within the scope of SERIESACTION, however, a custom configuration can be saved for this one invocation, which will overwrite the originally pre-filled data. Two objects are provided for the pre-filling of the protocol and reminder activity, which can be configures using the script. The configuration of the protocol activity is done via the object 'protocolConfigVO', and the reminder activity is configured via 'reminderConfigVO'. The following entry must be added to the script to pre-fill e.g. the title of the reminder activity:

reminderConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);

• In the following code examples, you can also use protocolConfigVO (for protocol activity) instead of reminderConfigVO (for reminder activity).

• Lookup field characteristics
  

  • The key name is forwarded as the value, e.g. 'A' in the field 'Priority'

  • The use of the empty key '?' is supported

  • The value will not be written to the field if the lookup values are invalid.

• Zero values are ignored. The existing field value remains intact

• The 'Edit' property for the field is always set, even if no field value can be entered.

The following configuration options are available for the protocol and reminder activity:

Pre-filled value for the field 'Status'

// reminderConfigVO.setStatus("Schlüsselname des Aktivitätenstatus oder Leerschlüssel '?'", editierbar?)
reminderConfigVO.setStatus("E", false);
// oder
reminderConfigVO.setStatus("?", false);

Pre-filled value for the field 'Starts on'

// reminderConfigVO.setStartDate("Datumswert" , editierbar?)

// Heutiges Datum
reminderConfigVO.setStartDate("NOW", true);       

// Fixes Datum
reminderConfigVO.setStartDate("15.08.2014 19:36:00", true);   

// Heutiges Datum + 5 Tage
long reminderDays = 5l;
Date reminderTimeDate = new Date(System.currentTimeMillis() + reminderDays * 24 * 60 * 60 * 1000);
String reminderTimeString = java.text.DateFormat.getDateTimeInstance().format(reminderTimeDate); 
reminderConfigVO.setStartDate(reminderTimeString, true);       

Pre-filled value for the field 'Title'

// reminderConfigVO.setSubject("Betreff", editierbar?)
reminderConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);

Pre-filled value for the field 'Description'

// reminderConfigVO.setDescription("Beschreibungstext", editierbar?)
reminderConfigVO.setDescription("Bitte erfassen Sie hier Ihren Text für die Erinnerungsaktivität", true);

Pre-filled value for the field 'Type'

// reminderConfigVO.setType("Schlüsselname der Aktivitätenart oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setType("SERIENBRIEF", false);
// oder bei Leerschlüssel
reminderConfigVO.setStatus("?", false);

Pre-filled value for the field 'Priority'

// reminderConfigVO.set("Schlüsselname der Priorität oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setPriority("A", false);

Pre-filled value for the field 'Reason'

// reminderConfigVO.setReason("Schlüsselname des Aktivitätenanlass oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setReason("PROJEKT", false);

Pre-filled value for the field 'Result'

// reminderConfigVO.setResult("Schlüsselname des Aktivitätenergebnisses oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setResult("MARKETING", false);

Pre-filled value for the field 'Employee assignment'

Specifying the 'Delegated by' employee

// reminderConfigVO.addDelegatedFrom("Kürzel des Mitarbeiters oder Variable", "Schlüsselname des Mitarbeiterbeziehungtyps");
reminderConfigVO.addDelegatedFrom("MAS", "EMPFÄNGER");
// oder aktueller Anwender per Variable
reminderConfigVO.addDelegatedFrom("USER", "BCC");
// oder Stellvertreter per Variable
reminderConfigVO.addDelegatedFrom("USER_DEPUTY", "BCC");

Specifying the 'Delegated to' employee

// reminderConfigVO.addDelegatedTo("Kürzel des Mitarbeiters oder Variable", "Schlüsselname des Mitarbeiterbeziehungtyps");
reminderConfigVO.addDelegatedTo("CHK", "EMPFÄNGER");
// oder Verwendung einer Variablen aus dem Mapping der Dokumentvorlage
reminderConfigVO.addDelegatedTo("SERIALEmployeeSales", "EMPFÄNGER");

Adding more employees

// reminderConfigVO.addEmployee("Kürzel des Mitarbeiters oder Variable", "Schlüsselname des Mitarbeiterbeziehungtyps");
reminderConfigVO.addEmployee("CHK", "EMPFÄNGER");
// oder Verwendung einer Variablen aus dem Mapping der Dokumentvorlage
reminderConfigVO.addDelegatedTo("SERIALEmployeeOffice", "EMPFÄNGER");

Adding employees

• In order to add employees, the relevant activities page must have been activated via script beforehand, e.g.

  ^{config.createProtocolActivity(true);}

• The following values can be used

  • Token for the employee name, e.g. 'MAS'

  • Variable 'USER' - token of the currently logged in user

  • Variable 'USER_DEPUTY' - shortcut of the deputy
    If user A logs in as a deputy of user B, the variable 'USER_DEPUTY' contains the shortcut of user B.
    If user A logs in without deputy control, variable 'USER_DEPUTY' contains user A's shortcut.

  • Variable from the mapping of the document template
    Defined variable names can be used in the mapping of the document template to allow a dynamic assignment of users for the activity generation in the serial action. An employee field from the search will then be assigned to this variable, which will be allocated to the generated activity (see also Add and edit document templates#Creating and editing the serial letter template dataset.)
    In order to use this variable, it is necessary that it exists in the mapping of the document template and that no multiple activity is created. The following variable names are supported:

    • SERIALEmployeeOffice

    • SERIALEmployeeSales

    • SERIALEmployeeKey

    • SERIALEmployeeExtra1

    • SERIALEmployeeExtra2

• Any number of employees can be added.

• The original employee assignment is overwritten, once employees are added.

• Only one 'Delegated to' and one 'Delegated from' can be added at a time. If the script command is sent multiple times, then the employee from the most recent script command will be the 'Delegated to/from' employee. The employees from the most recent previous script commands will remain in the list, but will no longer be the 'Delegated to/from' employees.

Complete example

public void init()
{
config.setTitle("Seriendruck Umschläge und Etiketten");
config.setType("LETTER");
config.setTemplate("SERIENBRIEF BLANKO (Beispiel)", true);
config.editSearch(true);
config.displayResult(true);
config.addSearch(false);
config.saveSearch(false);
config.setSubject("Text "+ MatchCode.value , false);
config.addFile("C:\\MeinPfad\\MeineDatei.txt");
config.setFormat("Controlfile","Excel", true);
config.setTestMode(false, true);
config.createProtocolActivity(true, false);
config.createRemindingActivity(true, false);
config.createSeparateActivities(true, true);
config.openWindowLevelForDocument(false); 

// Vorbelegung der Felder in der Protokollaktivität
protocolConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);

// Vorbelegung der Felder in der Erinnerungsaktivität
reminderConfigVO.setStatus("E", false);
reminderConfigVO.setStartDate("TODAY", true);
//reminderConfigVO.setStartDate("15.08.2014 19:36:00", false);
reminderConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);
reminderConfigVO.setDescription("Bitte erfassen Sie hier Ihren individuellen Text für die generierte Erinnerungsaktivität", true);
reminderConfigVO.setPriority("B", false);
reminderConfigVO.setType("RECHNUNG", false);
reminderConfigVO.setReason("BESCH", false);
reminderConfigVO.setResult("INFO", false);

// Vorbelegung der Mitarbeiterzuordnung in der Erinnerungsaktivität
reminderConfigVO.addDelegatedFrom("USER", "EMPFÄNGER");
reminderConfigVO.addDelegatedTo("SERIALEmployeeSales", "EMPFÄNGER");
reminderConfigVO.addEmployee("TMR", "BCC");
reminderConfigVO.addEmployee("GV", "BCC");
reminderConfigVO.setEmployeeChangeable(false);
}

Visibility of wizard pages

The edit capabilities for the input can be configured for many of the methods mentioned above.
Special feature: A wizard page will no longer be displayed if all input options on that page have been deactivated. The pre-configured settings on that page will continue to be considered. You can therefore completely hide the wizard, so that the opened document will be displayed as a result directly.

What components will have to be set to non-editable to hide a wizard page?

1. Template selection:

   • setTemplate

2. Select addressees

   • editSearch

   • displayResult

   • addSearch

   • saveSearch

3. Serial letter - options

   • setFormat

   • setTestMode

4. Enter document description

   • setSubject

5. Add files

   • changeFiles

6. Create activities

   • createLogActivity

   • createRemindingActivity

   • createSeparateActivities

7. The activity pages for protocol activity (protocolConfig) and reminder activity (reminderConfig)
   

   • setStatus (field 'Status')

   • setStartDate (field 'Starts on')

   • setSubject (field 'Title)

   • setDescription (field 'Description')

   • setType (field 'Type')

   • setPriority (field 'Priority')

   • setReason (field 'Reason')

   • setResult (field 'Result')

   • setEmployeeChangeable (button 'Employee assignment')

Templates and searches

A matching document template, for the complex search of which the following applies must be saved for the external invocation:

1. The primary key of the entity, from within which the external invocation originates, must be selected in the main search with the condition is one of and the template Placeholder(value to be set at runtime)

2. The primary key of the entity must be selected as the input parameter for the value "PK" in the main search.

• The field 'Entity' should not be populated with the empty key. The invocation would not be executed.

• It is possible to configure combinations, in which the user will be unable to continue in the wizard. For example, he could be forbidden to add new addressees and at the same time permit him to edit documents. If he does that, then the initially searched addressees will be deleted and he will be unable to add new ones. The user can only exit the wizard.

Type: SAP

The SAP interface allows any type of RFC invocations of CURSOR-CRM/EVI to SAP.

The technical implementation was done in the classes SAPInvocationExecutor, SAPInvoke and SAPCallConfigVO. The class SAPCallConfigVO simply serves as ValueObject, which is configured via scripting in the Call definition. All required information for establishing a connection and executing the RFC are drawn from this ValueObject.

Creating an SAP call

This is how you proceed:

1. Select the menu item Administration / External invocation.

2. Create an external invocation of call type SAP.

3. The configuration of the call is done in a script, which you save in the Memo field.
   The syntax and the available commands are identical to the script-based customizing. You can use the methods 'public void init ()' and 'public void handleResults ()' for the SAP interface. The method 'public void init ()' must be available, as it is needed for the call configuration. The method 'public void handleResults ()' is invoked after the RFC execution and can be used for utilizing the call results (see: Return values).

4. Save the invocation.

Configuration of a connection using JCo 2.X

The implicitly existing variable 'config' is used for the configuration of the invocation and the parameter transfer. The following properties can be set on this configuration object.

General parameters

These parameters can (or must) be provided in any case:

Direct connection

The following parameters can (or must) be provided for a direct connection to an SAP server:

Connection to a server group (load balancing)

The following parameters can (or must) be used to utilize load balancing (as an alternative for a direct connection) at the start:

There are two options for accessing a server group instead of an individual server. In both cases, the information for the general parameters must be added as well.

public void init()
{
config.setConnectToGroup(true);
config.setUrl("<Url zur Servergruppe>");
}

Activate load balancing via setConnectToGroup and add the group URL.

public void init()
{
config.setConnectToGroup(true);
config.setMessageServerHost("<IP des Messageservers>");
config.setR3Name("<Name des SAP Systems>");
config.setGroup("<Name der Servergruppe>"));
}

Activate load balancing via setConnectToGroup and add the message server, SAP system name and the group name.

Configuration of a connection using JCo 3.X

The implicitly existing variable 'config' is used for the configuration of the invocation and the parameter transfer. The following properties can be set on this configuration object.

General parameters

These parameters can (or must) be provided in any case:

Direct connection

The following parameters can (or must) be provided for a direct connection to an SAP server:

Connection to a server group (load balancing)

The following parameters can (or must) be used to utilize load balancing (as an alternative for a direct connection) at the start:

Experimental add-on parameters with JCo 3.X

The following parameters have been made additionally available but are still in the test phase. No guarantee can be given in terms of functionality.

These parameters can (or must) be provided in any case:

• Secure Network Connection (SNC) configuration

The following parameters allow the configuration of a secure connection:

• Target configuration

The following parameters allow the configuration of the target:

• Additional Parameters

The following parameters are additionally available:

Single Sign-On (SSO)

Client-side, via external invocations

Requirements

In addition to the general requirements above, SSO also requires:

• SAPCRYPTOLIB must be downloaded from SAP Marketplace and the file sapcrypto.dll must be added to the custExt directory of the client.

• The certificate for the current user must be available in the local MicrosoftStore (on client side) at runtime.

Configuration

The configuration of the invocation must

• activate SNC mode.

• Integrating the library for encryption

• Setting own name (the new constant USER can be utilized here to read the current user name)
  

• Setting the name of the connection partner

• Reading and setting the certificate

Configuration

config.setSystemNumber("03");
config.setSapServer("104.3.6.52");
config.setClient("003");
config.setSncMode("1"); //SNC aktivieren
config.setSncLibrary("c:\\My\\Library\\Path\\sapcrypto.dll"); //Bibliothek zum Verschlüsseln auf dem Client, alternativ weglassen, dann greift die Umgebungsvariable SNC_LIB.
config.setSncMyName("p:CN=" + SessionConstants.USER + ", O=Cursor, L=Gießen, C=DE"); //eigener Name
config.setSncPartnername("p:CN=User CA Cursor, O=Cursor, L=Gießen, C=DE"); //Namen des Partners
config.setSncQOP("9"); //optional
config.setX509Cert(SAPUtils.readCertificate()); //Lokal installiertes Zertifikat lesen
  
config.setConnectToGroup(false);
config.setRfcName("Z_TEST");

Via BPM processes on server side

Requirements

In addition to the general requirements above, SSO also requires:

• SAPCRYPTOLIB must be downloaded from SAP Marketplace and the file sapcrypto.dll must be added to the standalone\lib\dll directory of the server.

• The certificate for the current user must be available in the local MicrosoftStore (on client side) at runtime.

Configuration

The configuration is basically the same as for the client variant:

Configuration

Object config = SAPUtils.createConfig();
config.setSystemNumber("03");
config.setSapServer("104.3.6.52");
config.setClient("003");
config.setSncMode("1"); //SNC aktivieren
config.setSncLibrary("c:\\My\\Library\\Path\\sapcrypto.dll"); //Bibliothek zum Verschlüsseln auf dem Server
config.setSncMyName("p:CN=" + USER + ", O=Cursor, L=Gießen, C=DE"); //eigener Name
config.setSncQOP("9"); //optional
  
config.setConnectToGroup(false);
config.setRfcName("Z_TEST");

The two parameters 'setX509Cert' and 'setSncMyName', however, require a different procedure.

For 'setSncMyName', SessionConstants.USER must be used instead of USER:

Configuration

config.setSncMyName("p:CN=" + SessionConstants.USER + ", O=Cursor, L=Gießen, C=DE"); //eigener Name

The certificate must be read on the client computer. That will require a user action. The certificate must be forwarded to the following script action.

• This is what the entire process looks like:

• The certificate is read from the script of the user action and will then be written to the variable "sapcert". This name is freely selectable.
  

This variable is read again in the following script action and set in the configuration object:

Configuration

Object config = SAPUtils.createConfig();
//..

config.setX509Cert(ProcessUtils.getVariable("sapcert"));

Cross-server workflows on the server side

SSO cannot be used in server-side workflows, because there will be no client interaction.

Parameter transfer

Simple parameters can be set via an invocation of config.setSimpleParam("<Parameter name>", <Value>). The parameter name must match the name expected by the RFC module. The value (2nd parameter) can be assigned permanently or can be read from a field value in the currently open window via the notation ${Fieldname.Entity}. If the value is not numerical, then ${Feldname.Entity} must be enclosed in quotation marks.

SAP supports so-called structures as parameters. Structures are mainly a grouping of various simple fields under one name. In the init method, a structure parameter can be filled with the method setStructureParam(String structure, String field, Object value). The first parameter is the name of the structure (as defined by the RFC specification), the second value identifies the field within the structure and the last parameter represents the actual value.

Table parameters are another option for parameter transfers. Table parameters are an ordered list of structures. In addition to the parameters mentioned above, one further parameter for the row number is added for the configuration of a structure: setTableParamMapping(String tableName, int row, String field, Object value). The first parameter will once again state the name of the table parameter as expected by the RFC module. the second parameter states the row number (the first row has the number 0!). The third parameter identifies the field within a row, which is finally filled with the last parameter.

Return values

SAP supports return values in the form of structures and tables. These are made available after the invocation under a name in the context of the call definition. After a successful invocation, the variables String[] tableParams and String[] exportParams will contain the names of the relevantly returned parameters.

The variables String[] tableParams and String[] exportParams can also be Zero.

The following code displays the names of all returned table parameters in a dialog:

 public void handleResults()
{
for(int i = 0 ; tableParams != null && i < tableParams.length ; i++)
{
alert(tableParams[i]);
}
}

All structures and tables have names. The individual parameters are also made available under these names.

Examples

Example 1: Jump to SAP from within a business partner

public void init()
{
config.setClient("001");
config.setUser("user");
config.setPassword("userpw");
config.setSystemNumber("00");
config.setSapServer("172.16.0.22");
config.setRfcName("ZE_CURSOR_RFC_OBJECT_DISPLAY");
config.setSimpleParam("OBJECTTYPE", "01");
config.setSimpleParam("OBJECTKEY", "${CustomerNo1.Customer}");
}

The first lines are for the connection configuration. Then the RFC to be called is specified via config.setRfcName("ZE_CURSOR_RFC_OBJECT_DISPLAY") and two simple parameters are transferred. The first mapping OBJECTTYPE is fixed, the mapping for the parameter OBJECTKEY will then be read from the value in the field CustomerNo1 of the currently open business partner.

Example 2: Reading the table KNA1:

public void init()
{
config.setClient("001");
config.setUser("user");
config.setPassword("userpw");
config.setSystemNumber("00");
config.setSapServer("172.16.0.22");
config.setRfcName("RFC_READ_TABLE");
config.setSimpleParam("QUERY_TABLE", "KNA1");
config.setSimpleParam("DELIMITER", ";");
config.setSimpleParam("ROWCOUNT", 10);
config.setTableParamMapping("FIELDS", 0, "FIELDNAME", "NAME1");
config.setTableParamMapping("FIELDS", 1, "FIELDNAME", "NAME2");
config.setTableParamMapping("FIELDS", 2, "FIELDNAME", "MANDT");
}
 
public void handleResults()
{
TAB512.writeHTML("c:/temp/sap/TAB512.html");
alert("Ausgabewerte wurden als HTML-Datei gespeichert!");
}

The connection configuration is the same as in the first example. Then some simple parameters are used. The last three lines of the init method fill a table parameter. The names of the columns to be read are defined.

The method handleResults() is used for saving the result of the invocation (including a table with the name TAB512) alongside the invocation of the method writeHTML. This is an example of how return values can be handled in SAP invocations. The second row alert("...") is simply the invocation of a pre-defined method, the same way that it can be used in any script.

Example 3: Invocation of an RFC with a structure parameter:

public void init()
{
config.setClient("001");
config.setUser("user");
config.setPassword("userpw");
config.setSystemNumber("00");
config.setSapServer("172.16.0.22");
config.setRfcName("Z_FBO_TESTPARAM_01");
config.setStructureParam("VTR", "MANDT", "001");
config.setStructureParam("VTR", "VERTRAG", "${InstallationNo.Installation}");
}

The example demonstrates the configuration of a structure parameter. In the last two cells, the field MANDT in the structure 'VTR' is set to 001 and the field VERTRAG in the same structure is set to the value in the field InstallationNo.Installation. The placeholder is replaced during runtime in line with any call definition.

Changes to the version, interfaces and limitations of the target software may result in the SAP invocation not working for some versions, which would mean additional integration costs for CURSOR Software AG.

Integration of SAP JavaConnector 3.x

JavaConnector 3.x (instead of previously 2.x) will now be used if SAPGUI 7.1 or higher is installed by the customer. It contains new classes, which means certain changes in its use.

JCo 2.x

• Save librfc32.dll to windows\system32.

• Save sapjco.jar and sapjcorfc.dll to the folder CustExt.

JCo 3.x

• Save librfc32.dll and librfc32u.dll to windows\system32.

• Save sapjco3.jar and sapjco3.dll to the folder CustExt.

Script changes

There was a conscious attempt to not make any changes to existing scripts. That was not entirely feasible, as SAP made changes to the classes. The method "getField(..)" in a structure no longer exists. Instead, “getString(...)" (or "getInt(..)", etc.) must now be used.

Example:

public void handleResults()
{
String text = "";
 
RET.firstRow();
for (int i = 0 ; i < RET.getNumRows(); i++)
{
text += RET.getField("COUNTER").Value + " ";
Name2.Value = RET.getField("COUNTER").Value;
text += RET.getField("LINE").Value + "\n";
Name3.Value = RET.getField("LINE").Value;
RET.nextRow() ;
}
}

becomes

public void handleResults()
{
String text = "";
 
RET.firstRow() ;
for (int i = 0 ; i < RET.getNumRows(); i++)
{
text += RET.getString("COUNTER") + " ";
Name2.Value = RET.getString("COUNTER");
text += RET.getString("LINE") + "\n";
Name3.Value = RET.getString("LINE");
RET.nextRow() ;
}
}

Type: WEBSERVICE

See →Outgoing web services.