NCo 3.0 Logon

One of the new features implemented to combat the malevolent for RFC client attacks is the interface IDestinationConfiguration. This interface contains method IDestinationConfiguration.GetParameters(string destinationName) which allows .NET programmers to provide their own secure method for storing and retrieving logon information, be it encrypted database, encrypted file, or even LDAP.  There is also a corresponding interface and method to secure NCo 3.0 RFC servers.

Additionally, there is updated functionality to support single sign-on (SSO) and X.509 certificates.

Say Goodbye to Data Containers and Generated Code

In SAP Connector 2.0, working with RFCs required the generation of proxy code via the SAP .NET Connector design-time tool.  This tool would convert the IMPORTING, EXPORTING, CHANGING, and TABLES parameters from the RFC you were calling/serving to .NET representations of the same.  With NCo 3.0 there is no longer any kind of generated code.  Instead of one generated proxy method for each function module, there is one single RfcFunction class, whose Invoke() method dynamically executes every given ABAP function module. Additionally, all ABAP parameters will be represented by the class RfcStructure instead of a dedicated generated class for every structure; All tables will be represented by class RfcTable.  So, instead of hard-coding all of the data and variable bindings statically at design time, NCo 3.0 now handles everything dynamically at runtime.

NCo 3.0 uses SAP’s data dictionary to determine the function interface for the called RFCs.  While this data is cached locally for performance reasons, NCo 3.0 is robust enough to detect changes in RFC interface signatures so your code will still execute if you’ve added, deleted, or changed RFC parameters.  If there arises a situation where the dynamic lookup of RFC interface signature is not wanted, there is also an option to hard code the RFC parameter metadata.

The biggest benefit of NCo 3.0′s new dynamic function handling is that NCo 3.0 no longer has a design-time component.  This releases the Visual Studio version restriction that .NET 2.0 had.  Let me rephrase that, NCo 3.0 will work with any version of Visual Studio you like! The only requirement is that at runtime, a .NET Framework version is installed that is compatible with the NCo 3.0 libraries.

Anxiously Waiting

NCo 3.0 figures to be a much-needed update to a vital SAP integration technology.  I, for one, cannot wait for the new functionality to be generally released.  Once NCo 3.0 is released we’ll be posting blogs highlighting the new features.  We’ll also include helpful information regarding a .NET Connector 2.0 to NCo 3.0 upgrade.  In the meantime, if you have any leave any questions or comments you have regarding NCo 3.0 below.  You may also email me directly at cstasila@dataxstream.com if you’d like to set up a detailed conversation.

Object Name Prefixes

I have seen a lot of places use prefixes or suffixes before objects such as or dt_ or _mt. I have never really been a fan of these prefixes and suffixes, and apparently neither is the above linked naming convention guide. The reason being is that they are unnecessary. It would be difficult to confuse a message type with a data type in a real interface scenario, even if troubleshooting an unknown broken object. Plus it makes message mapping unnecessarily confusing and long since it’s not clear whether to add the prefix, i.e. MT_one_to_MT_two. Good descriptive names are usually all that you need e.g. DEBMAS_to_Customer. The only possible exception to a no-suffix-or-prefix-policy is the service interface, as sometimes it is useful to know which direction and type a service interface is. An argument for a prefix or a suffix to describe a service interface would be to assist in understanding the flow from an SAP perspective in the event that someone who didn’t develop the interface had to come behind and troubleshoot. A argument against would be the fact that it looks silly if you use it for a web service, because you have a name that doesn’t mean anything to a third party user (note operation mappings are told to omit the prefix of direction and mode in the SAP guide).

One interesting thing that I noticed in my investigation of PI 7.1 EHP1 is that it appears that naming conventions on PI can be validated. If the object names do not conform to a naming convention a message will appear. Ter perform this check in the ESR go to menu Tools>Component Check.

Select “Governance” and “Interface Name Checks”:

If the service interface does not end with (In/Out)(SYNC/ASY) the interface check will show as an error (does not impact interface processing). I created 2 interfaces: one good and one bad to show this error.

My suspicion is that SAP will put more in place to force consistent naming standards depending on the service interface pattern in future releases.

Using a software component and Namespace for each “side” of an interface

All objects of an interface should not be grouped in a single namespace. They should to be split among the Software Component Versions of the systems being interfaced. Otherwise when you go to configure, you will not be able to see your operational mapping (OM) in the dropdown box without having to select all in the dropdown menu. A general rule of thumb is: if it’s not easy to configure, odds are you have probably done something wrong. Another reason why an object might not appear in the dropdown menu (for example for an operations mapping on an interface mapping) would be if the installed checkbox is not clicked on the SLD. When done correctly, most interfaces should be able to be configured quickly and intuitively in the integration directory (ID) without the need to select from all SWCV from dropdown menus on the integration builder.

Whatever naming convention you choose to use for the ESR, the important thing to remember is that adhering to the standard makes production support and troubleshooting faster and easier.

Part One – The Integration Directory (for PI 7.1 or greater)

I decided to start with the Integration Builder because it’s the easier component with which to bring everything into alignment (versus the ESR). Most of the time there are only two things to name: the scenario and the communication channel.  Unfortunately, it is still incredibly easy for objects to become disorganized.

Configuration Scenarios

The whole purpose of a configuration scenario is for organization. An interface will run whether it is in a scenario or not, however troubleshooting is much more difficult when objects are not properly organized. It is important to use a naming convention that addresses the business purpose of the interface and is specific to the flow of the interface (to help with troubleshooting issues and make flows easily traceable).  To accomplish all of these requirements, DataXstream recommends a naming convention that includes the specification number which originated the development request and a route number. The route number is used in interface diagrams and documentation and assists production support with identifying objects in the event that a business scenario involves multiple destinations.  We also recommend including a statement to describe the flow for the route, as well as the description of what the interface does. Some examples of a naming convention we might use would be:

0001.001_ECC_to_Partner1_TransactionalDataDistribution 0001.002_ECC_to_Partner2_TransacationalDataDistribution 0002.001_Partner3_to_ECC_SomeInboundInterface 0003.001_Partner4_to_Partner5_SomeNonSAPInterface

The other thing of note is that all objects should exist in a scenario, even if in a test_DONOTTRANSPORTTOPRODUCTION_prototype_interfacedescription scenario. Proper organization makes it a lot easier to identify, modify, turn on and off, and troubleshoot interfaces. Fully configured interfaces running in objects view take more time to understand and are more time consuming to fix.

Communication Channels

Communication channels should describe the purpose, type, and direction of communication. However a lot of people include unnecessary components in the communication channel. For example, since there are usually only two objects with names in the IB, it is not necessary to prefix a communication channel with cc_ as it is unlikely to ever be confused for a scenario. A lot of people also include the communication component in the name of the communication channel, but that also seems redundant, since only communication channels exist under communication components. Some things that are valuable in looking at communication channel naming convention are knowing a brief description of the process it involves, a direction of the communication channel, and the type of adapter being used. Some examples of naming conventions we might use are:

Logistics Company

• PO_file_sender

Database System

• materialSqlXml_jdbc_receiver

ECC system

• IDoc_receiver

As you can see, it is possible to keep the name descriptive and helpful without making the name overly verbose when it comes to communication channels.

The order in which the naming components are ordered depend as much on personal preference as anything else.  For example, let’s examine a sender file channel that pertains to purchase order data.  Some of the naming convention options are:

• Sender_File_PO: groups all sender and receiver channels together, then groups by adapter type
• File_Sender_PO: groups communication channels by adapter type, then by sender and receiver
• PO_File_Sender: groups by logical interface payload, then adapter type

Other Things To Watch Out For

• Configure the unnecessary- We all know that no sender agreement or channel is needed for certain communication methods like iDoc or SOAP to the IE, but if you can, add them to the scenario anyways. It makes it easier for a new developer (think of someone new to production support) to understand what’s happening with an interface, when they can see a consistent flow of the interface sender agreement to receiver agreement on all interfaces in a landscape. I know from working with working with soap, it’s kind of nice being able to grab the wsdl from the sender agreement, even though that component is technically optional.

• Don’t force an interface to work- If you are configuring a determination or agreement and are not seeing what you expect from the drop down menu, it may be because you haven’t properly defined the SLD or IR. Don’t be lazy and select the interface from all namespaces or SWCVs just to make the interface work; go back and figure out why its not dropping down on the drop down box and correct it.

Establishing and adhering to a well thought-out and consistent naming convention can save you a lot of time during the support of your SAP PI interfaces.  In Part II of this blog, I will discuss naming conventions in SAP PI’s Enterprise Service Repository (ESR).

How do you know when an Outbound IDoc has physically left SAP?

It’s a simple fact that if your subsystem never receives an IDoc from SAP, the subsystem will not be able to route or process the IDoc.   I have always gone by the notion that once the subsystem has successfully received the IDoc, the subsystem now has all the responsibility to process and route the IDoc, but before that time, SAP has the responsibility to ensure that the IDoc is fully dispatched.  The subsystem should have processes in place to determine if the IDoc has been received at the target system successfully or not.  In this blog I will focus on the handshake between SAP and the subsystem.  This will entail Outbound IDoc status and a couple of batch jobs that should be setup to ensure a better chance of a successful handoff between SAP and the subsystem.

First, let’s cover the normal, expected progression of statuses for outbound IDocs.  The following graphic shows the collection of status records for a random outbound IDoc.

The status records at the bottom of the list depict the IDoc status before the status records at the top of the list.  So, in this example, the IDoc started in status “01 – IDoc generated”, then progressed to status “30 – IDoc ready for dispatch (ALE service).”  These two statuses usually are created in rapid succession for outbound IDocs and mean that the IDoc has been created in the SAP system and is ready to be sent via tRFC to the subsystem.  The next two IDoc status, 03 and 12, can be a little confusing.  They both seem to mean that the IDoc has been dispatched from SAP.  What is the difference?  I have found that sometimes there is some confusion on weather the IDoc has left SAP or not.  After I explain the difference, I will show 2 batch jobs that should be setup in order to update the status if the Outbound IDoc has physically left SAP.

So what do statuses ‘03’ and ‘12’ really mean?

The status ‘03’ actually means “Data passed to port OK” which basically means that the IDoc has been dispatched to the tRFC queue and an attempt was made to send the IDoc to the subsystem.  However, that does not necessarily mean that the IDoc has left SAP.   There could be many reasons why SAP would fail to send the IDoc.  One example could be that the subsystem was down during the transmission of the IDoc.  Errors during data transmission would cause the IDoc to remain in the tRFC queue.  Thus, the IDoc would still remain in SAP and remain with a status of ‘03’.

When the Status changes to ‘12’; a successful connection was made to the subsystem and the IDoc was sent.  This status represents that the Outbound IDoc is no longer in the tRFC queue  and, therefore, has physically left SAP.  The IDoc is in the hands of the subsystem which is now responsible for processing or routing the IDoc.

But what if I never see a status of ‘12’ on IDocs that were successfully sent?

For one reason or another, sometimes the batch job to update the status to ‘12’ is not scheduled.  In Production this batch job is usually set up, however in the QA or Dev environment this may or may not be setup depending on the client.

1)  The following job should be setup in order to process a status ‘12’.  I typically set this to every 10 minutes depending on the client.

Program:  RBDMOIND – Schedule this program in order to check whether the IDoc have been successfully sent out of the tRFC queue.  If the IDoc has been sent successfully to the subsystem, the program RBDMOIND will change the status of the IDoc from status ‘03’ to status ‘12’.  This means that the handshake with subsystem was successfully and the IDoc has physically left SAP.

2)  There may be times when the subsystem is unavailable at the time the SAP is trying to send the Outbound IDoc.  By default, SAP will only make one attempt to transmit the IDoc.  By scheduling the following program in a batch job, SAP will try to resend the Outbound IDoc again at a specified time interval.  I also usually set this at job every 10 min, depending on the client.

Program:  RSARFCEX – Schedule this program in a batch job in order to resend any IDocs that have are stuck on the tRFC queue.

Ok I have set up these jobs, but the status does not change.  Now what?

Sometimes an Outbound IDoc could remain stuck on the tRFC queue and never get sent out successfully.  Some issues could be that the RFC Destination for the subsystem is configured incorrectly or there could be an authorization issue.  These types of errors need to be fixed before the batch job for RSARFCEX will send the IDoc out successfully.  You may need to get some additional detail of the problem.  Execute the following transaction below.

Transaction SM58 – This will check what is currently on the tRFC queue.   Once you display the list, you also have the ability to drill down and get some additional detail of what has caused the failed transmission.

Conclusion

Typically you won’t see many issues with Outbound IDocs.  From time to time, IDocs will get stuck on the tRFC queue and if not managed properly, could be stuck there a long time.  This blog should give you more visibility in respect to IDoc status to ensure that the Outbound IDoc has successfully left SAP for processing.

Too many cooks spoil the broth

The common meaning extracted from this saying is that too many people working on a single task tend to make a mess of it.  But, what happens when you have too many developers working in a single piece of ABAP code?  That’s right, you get a big mess.  This issue is especially difficult to deal with when there are multiple functional requirements leveraging the same custom code object, form-based user-exit, or function-based user-exit.

While current releases of SAP (those built on SAP NetWeaver 2004s and later) have good built-in handling of enhancements and customizations via implicit and explicit enhancement points and BADIs, there still exists many old-school user-exits.

Multiple Developers; One Code Object

I recently worked on a project where three separate developers were creating three separate interfaces based on the outbound delivery IDOC.  While the development for all three interfaces was occurring at the same time, the go-live date for each of the interfaces were different (we’ll discuss that project management glitch at another time).  Each interface required a separate set of custom fields and, therefore, it’s own IDOC extension.  The problem is there is only one appropriate user-exit in IDOC_OUTPUT_DELVRY and three developers needed to be developing in it at the same time!

How did we solve this problem?

An Object To Call One’s Own

To allow each developer his own development object and transport timeline, I decided to implement a custom multiple-use, filtered BADI inside the SAP user-exit function EXIT_SAPLV56K_002.  Actually, you can implement your own BADI almost anywhere you need alternate logic execution–even custom code!

So you might be saying, “Create my own multi-use, filtered BADI definition? Sounds complicated.” Well, it’s easier than you think!

NOTE: This solution was done on an ECC6 system based on SAP NetWeaver 2004s.  The steps to implement this type of solution in ECC5 (SAP NetWeaver 2004) are very similar.

Create A Custom BADI Definition

1. To create a new enhancement spot definition, use transaction SE18.  I named my enhancement spot Z_EXIT_SAPLV56K_002 because the enhancement spot will be used in user-exit function EXIT_SAPLV56K_002.
2. In the ensuing dialog box, enter a description and choose BAdi Definition for the Technology
3. Next, create a new BADI definition.
4. Specify that the new BADI definition will be multiple use and limited to filtered use. Making the BADI definition multiple use means that each developer can create his or her own BADI implementation.  Each BADI is implemented in its own class.  This promotes code separation and the proper reuse of shared development objects. Making the BADI definition limited to filter use ensures that the BADI implementations are separate and cannot affect every interface using the user-exit.
5. Now, create a new filter. BADI filtering in SAP NetWeaver 2004s is much more powerful than in previous versions of SAP.  Read more about BADI filtering here.
6. The BADI we are defining will be used to populate IDOC extensions.  Each IDOC extension has its own message type (e.g. ZMHL_DESADV, ZQTC_DESADV, ZMHL_SHPORD), therefore the message type of the IDOC being processed is a good value to filter on.  I named my BADI filter EDI_MESTYP. SAP allows for the automatic checking of BADI implementation filter values.  The standard domain EDI_MESTYP has a value range of table EDMSG attached to it.  This is exactly the range of values I want as allowable values, so I configure the BADI filter to automatically check the filter values against dictionary object EDI_MESTYP.
7. Next, create the BADI interface that will be inherited by each implementing class
8. The original user-exti function EXIT_SAPLV56K_002 is executed after each segment is added.  Our BADI will do the same.  Create a new public interface method SEGMENT_ADDED.
9. The BADI we are creating is replicating user-exit function EXIT_SAPLV56K_002.  Here is the function interface for EXIT_SAPLV56K_002: Here is the same data being passed via the interface method.
10. Lastly, the BADI has to be called from the existing user-exit.  I will not cover the steps required for implementing user-exit function EXIT_SAPLV56K_002 here, but once you have the user-exit implemented, add the following code.  This code should be the only logic directly inside the user-exit.  Any data processing logic should be implemented via a BADI implementation:

    DATA: GO_BADI TYPE REF TO Z_EXIT_SAPLV56K_002.
    DATA: L_STR TYPE STRING.
    L_STR = MESSAGE_TYPE.
    
    * Get BADI class based on IDOC message type
    GET BADI GO_BADI
       FILTERS EDI_MESTYP = L_STR.
    
    * Execute SEGMENT_ADDED BADI method
    CALL BADI GO_BADI->SEGMENT_ADDED
       EXPORTING
         MESSAGE_TYPE       = MESSAGE_TYPE
         SEGMENT_NAME       = SEGMENT_NAME
         DATA               = DATA
         TAB_IDOC_REDUCTION = TAB_IDOC_REDUCTION
         FLT_VAL            = MESSAGE_TYPE
       CHANGING
         CONTROL_RECORD_OUT = CONTROL_RECORD_OUT
         IDOC_DATA          = IDOC_DATA[].

We’re done with creating the BADI definition!  Save and activate your work. I bet you’re saying to yourself, “Wow, that was easy!”

BADI Implementation

Implementing the BADI you just created in the steps above is just like implementing any other BADI in SAP, so here are the Cliff Notes version of implementation instructions.

1. Using transaction SE19, create a new enhancement spot implementation for Z_EXIT_SAPLV56K_002.
2. Enter the BADI implementation details.  This particular BADI implementation is for RICEF ID MHL-IO-007, so I added that identification to the BADI implementation name and implementing class name.
3. In the BADI definition, we required each BADI implementation to be filtered on message type. This particular BADI implementation is for message type ZMHL_SHPORD.  Create the filter combination for the BADI implementation.
4. This ensures that the other interfaces using this BADI (ZMHL_DESADV, ZQTC_DESADV) will not execute the code implemented with this BADI.
5. The final steps are to add the code to the SEGMENT_ADDED method just like you would in user-exit function EXIT_SAPLV56K_002.  Once you are done, save and activate your changes!

Summary

As you can see, with a few extra steps, it is possible to have your cake and eat it, too, by create a custom BADI definition that can be used by other developers.  All this talk of food is making me hungry.  Is it lunchtime yet?

The SAP .Net Connector simplifies creating C# programs that can interoperate with an SAP host. The SAP .Net Connector is available from the SAP Service Marketplace. You must have access to the SAP Service Marketplace to be able to download the SAP .Net Connector. The SAP .Net Connector must be installed on your development machine before we begin.

RFC is a Remote Function Call. In this case, the SAP process is a ‘client’ that is making an RFC call to our custom ‘server’ code. Our code uses the SAP .Net Connector to register on an SAP Application Gateway.

The TLA system we have been creating exists solely to demonstrate certain programming techniques involving the SAP .Net Connector and C#.  We will cover three separate parts of the solution: defining the function to SAP, creating a proxy object used to access SAP, and creating our C# code to perform the RFC function.

Defining the Function in SAP

Before we build our RFC server, we will define our RFC function in the SAP system. There are two parts we will need to create:  the Function Signature, and the RFC Destination.

Defining the RFC Function Signature

Open the SAP SE37 Function Builder screen. For the Function Module field, enter Z_RFC_TLA_HELLO_WORLD and click Create. For the Function group, press the browse button to the right of the field, then select an appropriate function Group. Enter a short text description and click Save to save the function signature.

On the Attributes tab, be sure to select the Remote-enabled module radio button.

Now we will be asked to define the parameters that are used. SAP refers to values passed to the RFC call as Import values. Values that are returned from the RFC call are called Export values.

In the Function Builder screen, on the Import tab, define a Parameter named Name. Fill in the appropriate Type and Associated Type values. Be sure to check the Pass Value check box.

On the Export tab, create a Parameter named Hello_World. This will end up storing the result of the RFC call. Define the field in the same way as the Name import field.

Save your RFC Function. Then you need to activate your RFC function. To do that, from the SE37 screen, enter the function module name. then click the Activate button.

Defining the RFC Destination

SAP can direct an RFC call to different destinations. We will create an RFC Destination using SAP function SM59. This RFC Destination is used by the SAP system to route an RFC call to our program, which previously registered itself on the SAP Application Gateway.

In the SM59 screen, click the Create button.  Enter RFC destination of TLARFCSERVER. The Connection type is T for TCP/IP. Enter a description.

On the Technical settings tab, select Activation Type of Registered Server Program.

For the Registered Server Program Program ID, enter TlaRfcSrv. The Program ID we use here must match the Program ID used when our server code connects to the SAP Application Gateway.

If you try the Test connection button, it will fail, since we have not yet registered our program on the Application Gateway. Later, we can come back to SM59 and test this and see that our RFC destination is available.

C# Code

We will create an application that can be called from an SAP host. The SAP host will pass in a name, as a string. Our application will return a hello greeting back to the calling program.

Our solution will consist of two parts.

1. The first part is the SAP .Net Connector Proxy project, named TlaRfcServerSapProxy. This will produce a Dynamic Link Library that encapsulates what we need to know to interoperate with the SAP host.
2. The second part is is our custom code project, named TlaRfcServer. This contains the code which will execute when called from the SAP host via RFC. Save the RFC destination.

Creating the SAP Proxy Project

We will use Visual Studio 2003 to create a DLL that manages the interactions with the SAP host. The SAP .Net Connector version 2.0 works with Visual Studio 2003 or 2005. To use the .Net Connector in our preferred environment of Visual Studio 2008, we will create the proxy DLL in 2003 and add that to our 2008 project. The techniques are described in our earlier post, Using the SAP .Net Connector in Visual Studio 2008.

In Visual Studio 2003, start a new Class Library project named TlaRfcServerSapProxy. Delete the default Class1.cs file that is created automatically.

From the Solution Explorer, Right-click on References and choose Add New References. Under the .Net tab, highlight SAP.Connector.dll and SAP.Connector.RFC. Click the Select button, then OK to add the SAP .Net Connector references.

Now add the SAP Connector Proxy to our project. Right click on the project and choose Add / Add New Item. Under the templates, highlight SAP Connector Proxy. In the Name field, give our proxy the name TlaRfcServerSapProxy.sapwsdl. The name we use here will become the object type name for our SAP Server Proxy object we use when we build our RFC server code.

The TlaRfcSerfverSapProxy.sapwsdl file will be displayed in Design mode. Right click on the Design surface and choose properties. This displays properties of our SAP Connector Proxy. Change the Proxy Type to Server.

Now we need to add in a reference to our SAP host so that we can pull in the signature and object model for our RFC function. Open the Server Explorer windows and expand SAP / Application Servers. Right-click on Application Servers and choose add New Server. Enter in the connection information for your SAP host. Click OK.

Expand the newly added SAP Server and right-click on Functions. Choose Add New Function Filter. In the Name Filter field, enter *HELLO* . The * is used as a wild card. Click OK to display our Z_TLA_RFC_HELLO_WORLD function in the Server Explorer.

Highlight the Z_TLA_RFC_HELLO_WORLD function in the Server Explorer, and drag it onto the TlaRfcServerSapProxy.sapwsdl design surface. This will add the necessary function signatures and object type definitions to the project.

Now attempt to build the project. It will fail, as we have not yet created the code to implement our remote function. But, when we ran the build, the SAP Connector generated an implementation stub for our server method. A new class was automatically added to our project, named TlaRfcServerSapProxyImpl.cs.

However, we desire to implement our RFC server using Visual Studio 2008.

So, we will modify this code so it will build, and later we will override the implementation from our Visual Studio 2008 project.

If you double-click on the build error, it will take you to the offending line of code. All we need to do is set the result of Hello_World to some value.  To prevent confusion with our Visual Studio 2008 code, we will just return foo.

Now build the TlaRfcSapServerProxy project and it will create TlaRfcServerSapProxy.dll, which we will use in our Visual Studio 2008 project.

Creating the RFC Server Project

Using Visual Studio 2008, create a C# console project named TlaRfcServer. In the Solution Explorer, right-click on References and choose Add New Reference. Using the Browse tab, select both SAP.Connector.dll and Sap.Connector.Rfc.dll, typically found in C:\Program Files\SAP\SAP .Net Connector 2.0.

Add a reference to the TlaRfcServerSapProxy.dll created earlier, also using the Browse tab. Add a reference to System.Web.Services using the .Net tab.

In our C# code, we need to provide the code to implement our RFC function, which we do by inheriting from TlaRfcServerSapProxyImpl and overriding the Hello World function.

On Line 3, with have our ‘using’ directive to include our custom proxy.

On line 8, we are creating a new class named SAPProxy, which is derived from our TlaRfcServerSapProxyImpl class that was created in our Visual Studio 2003 class.

On line 12 is the override of the Z_Tla_Rfc_Hello_World call. We provide our functionality and place the result in the Hello_World variable.

That concludes our class that will implement the RFC functionality.

Now we will finish off our console program so that we can establish our code on the SAP Application Gateway and execute it.

To do this,we will pass in command line arguments to our Main routine. These arguments are passed to the SAPProxy constructor, which uses them to connect to the correct SAP Application Gateway.

Each of our SAP Proxy objects are hosted by an SAPServerHost object, which is part of the SAP .Net Connector. The SAPServerHost object governs the connection to the SAP host.

Once we create the SAPProxy object and attach it to an SAPServerHost, we can start the host and that will cause our program to register and be available on the SAP Application Gateway.

Our program will continue to be available on the SAP Application Gateway as long as we have it running (until we press the enter key, in our example).

On lines 22-25, we instantiate our proxy and SAP host. Notice how we pass in the command line arguments to the SAPProxy constructor (line 25).

We start the proxy on line 29. After we have done that, we can go back to the SAP SM59 function and test our RFC destination. If things are working, that test will success.

Our code will continue to be available until we press enter at line 37, after which we stop the SAP host.

Command Line Arguments

The command line arguments consist of three parts, and are specified in the Visual Studio environment under the Debug tab of the Project Properties display.

The three parts are

-aProgram ID

-XPort

-GHost

The Program ID specified here must match the Program ID we used when creating the SAP RFC Destination. In our case this is specified as –aTlaRfcSrv.

The Port field tells SAP what TCP/IP port to use. This is specified by –XSAPGW00. The SAPGW part specifies port 3300, we add whatever the 00 is to get the actual port number. In our case we are using port number 3300, so we use –XSAPGW00. If we wanted port 3302, we would have used –XSAPGW02.

The Host field is the DNS name or IP address of the SAP server.

So, your parameters will be different but they will look something like –aTlaRfcSrv –XSAPGW00 –Ghostname

Now build and run TlaRfcServer. A console window will appear.

Go back to SAP and bring up the SM59 screen. Expand the TCP/IP connections and find TLARFCSERVER. Double click that to display the definition. When you click the Test Connection button, you should see something like :

which indicates a successful test of the RFC destination.

Now we need to test our actual RFC function. Bring up the SAP SE37 screen. In the Function Module name, enter Z_TLA_RFC_HELLO_WORLD, which matches the name of the function signature we created earlier.

Press the F8 key to test the function. The Test Function Module screen is displayed.

For the RFC Target sys, we use the RFC Function destination we created earlier, TLARFCSERVER.

For the name field, type WORLD. Press F8 to execute the RFC call.

This indicates a good test of our RFC function.

Troubleshooting

If things don’t work, check the following:

Program ID in RFC Destination matches –a parameter of TlaRfcServer command line.

Port number (SAPGW00) on TlaRfcSever comand line is set to correct port number.

Any firewalls in between the SAP host and the RFC Server program need to allow traffic in both directions over that port.

Summary

In this blog posting we have shown how you can call custom C# code from an SAP process.

Please note that I was unable to find the wizard for setting it the Services registry in PI 7.1 EPH1, which means I did it manually.

Make sure everything is correct in the Services Registry Management

Go to the NWA (http://host:port/nwa).

Go to SOA Management> Technical Configuration>Services Registry Management. In theory, there is nothing to do here, however I did specify the discovery URL api parameter as the hostname of the server (no port). If you have changed some settings, on the maintenance tab you can click reinitialize, which should reset any changes you have made back to the initial state.

Configure the ServicesRegistrySiPort

Go to SOA Management> Application and Scenario Communication> Single Service Administration

Click the Consumer Proxies tab.

Search for “ServicesRegistrySi”.

Click on the result and click the Configuration Tab and click on ServicesRegistrySiPort.

The service endpoint name should be ServicesRegistrySiPort.  Don’t change it.

Click security.

You have to give it an http authentication. If you don’t give the authentication, you will eventually have problems like not being able to publish to the SR, even though you may be able to access the registry.

Click on the user ID/ password, click details, and input your http authentication parameters.

Configure the third party UDDI (Only if not using SAP’s UDDI)

If you are using a non-sap UDDI, you will need to go to NWA>Destination Template Management and create a UDDI_DESTINATION and a CLASSIFICATION_DESTINATION to point to the respective urls of your uddi. Don’t forget to click security and select User ID/Password Authentication for both destinations. Otherwise, you will get a 401 not authorized error when you try to access the services registry–similar to if you mistyped your password at ServicesRegistrySiPort.

Security

Make sure that your user has  UDDI_TierN and SERVICES_REGISTRY_READ_WRITE authorizations or you will get a 401 not authorized error.  Of course. in your system you should use a technical user instead of your userid as which I did for the purposes of this blog.

Please note, I did run into an issue where it suddenly stopped working a day everything was configured. All I can say is Gremlins. I switched the user to a technical user with the authorization listed above on the ServicesRegistrySiPort as well as on the destination templates and I haven’t had a problem since.

What a great idea!  Too bad I hate this suggestion… and it’s all SAP’s fault!!

You see, SAP transaction BD53 just does not play well with others.  My full HRMD_A solution used a custom filter object (transactions BD95 and BD59) and a custom outbound IDOC formatting function module to convert change pointers into IDOCs (transaction BD60).  The dirty little secret of transaction BD53 is that every time you save and update the IDOC reduction in transaction BD53, SAP goes and screws up a bunch of configuration  displaying a message that says “Interface changed for message type <your_message_type>:  Settings reset”

Wait! What!?!

What does that message even mean?  Well, that message is telling you in very cryptic language that SAP has gone and reset the settings in BD59 and BD60 to the SAP standard! So, every time the field reductions were updated, kiss your custom filter assignments and custom IDOC processing function goodbye!

Why couldn’t the message say:

Hey Buddy! You know all that custom configuration you did to get your interface working just so? Well, its gone and you’re going to have to redo it all in the following transactions: BD59 BD60 etc.

I guess SAP is just far too polite.

So, be very cautious when you pair IDOC reduction with custom filter assignments and custom IDOC formatting function modules and be aware that every time the IDOC reduction is updated, you will need to go back in to reconfigure transactions BD59 and BD60.

For more information, see SAP OSS Note 655321

The reduction at segment level (see also Note 301223) was facilitated in order to be able to copy message type HRMD_A. This involved setting the reduction at field level, which was not taken into account in the code because it is not possible to centrally determine which fields are mandatory and which are dependent for all country versions. In addition, for one info type there may several records for different periods of time, which may also cause a problem when you are reducing fields.

So, in essence, field-level reduction isn’t supported for HRMD_A.  The solution supplied in the OSS note suggests creating user-exit code to filter out the unwanted fields.  I already have implemented BADI HRALE00OUTBOUND_IDOC to add some other processing logic (if you’re lucky I’ll cover that logic in this blog, too), so I have a module in which I can place the code. And while the code to loop through an IDOC and clear out all instances of E1P0002-PERID, E1P0002-GBDAT, and E1P0002-GESCH is very easy, I can’t help but think I can make the code more useful.  You see, I hate unitasking code.  I can see it now.  If I take the shortcut path and wrote the unitasking code to clear those 3 fields, the code won’t be in production for more than a month before the requirements change and now there is another field that needs to be filtered out as well.  With unitasking code, I would have to crack open the code, create a transport, unit test, transport to Q, integration test, wait for a transport window, blah, blah, blah.  Ugh!  What a waste of time for a minor change.  We can do better.

I decided to create a multi-tasking module that will work for HRMD_A message types.  The fields to be cleared will be stored in TVARV in the format <SEGMENT>-<FIELD> (e.g. E1P0002-PERID).  That way, whenever the HR functional team wanted to filter out a new field, all they had to do was to update a TVARV variable.

To implement the solution, I created a new method called CLEAR_IDOC_FIELDS in my class implementation for BADI HRALE00OUTBOUND_IDOC.  CLEAR_IDOC_FIELDS has the same method signature as IF_EX_HRALE00OUTBOUND_IDOC~IDOC_DATA_FOR_RECEIVER_MODIFY:

The code is pretty straight forward.  To allow multiple interfaces to coexist in method CLEAR_IDOC_FIELDS, the TVARV variable that stores the fields to clear is in the format ‘ZHR_CLR_’ concatenated with the IDOC message type.

METHOD CLEAR_IDOC_FIELDS .
*----------------------------------------------------------------------*
* Class:     ZCL_IM_HRALE00OUTBOUNDIDOC                                *
* Method:    CLEAR_IDOC_FIELDS                                         *
* Author:    Craig Stasila                                             *
*----------------------------------------------------------------------*

  TYPES: BEGIN OF TY_FILTER,
           TABNAME   TYPE DFIES-TABNAME,
           FIELDNAME TYPE DFIES-FIELDNAME,
           POSITION  TYPE DFIES-POSITION,
           OFFSET    TYPE DFIES-OFFSET,
           LENG      TYPE DFIES-LENG,
        END OF TY_FILTER.

  DATA: WA_FILTER      TYPE TY_FILTER,
        LT_FILTER      TYPE TABLE OF TY_FILTER,
        LS_TABNAME     TYPE DDOBJNAME,
        LS_SAV_TABNAME TYPE DDOBJNAME.

  DATA: LS_NAME   TYPE TVARV-NAME,
        LT_TVARVC TYPE TABLE OF TVARVC,
        WA_TVARVC TYPE TVARVC.

  DATA: LT_DFIES TYPE TABLE OF DFIES,
        WA_DFIES TYPE DFIES.

  DATA: LR_SEGNAM TYPE RANGE OF EDIDD-SEGNAM,
        WR_SEGNAM LIKE LINE OF LR_SEGNAM.

  FIELD-SYMBOLS: <FS> TYPE LINE OF EDIDD_TT.

* Fields to clear are in variable
  CONCATENATE 'ZHR_CLR_' MESTYP INTO LS_NAME.

* Get list of fields to clear from TVARV
  SELECT * FROM TVARVC
    INTO TABLE LT_TVARVC
   WHERE NAME = LS_NAME
     AND TYPE = 'S'.

  CHECK SY-SUBRC = 0.

* Build list of fields to clear
  LOOP AT LT_TVARVC INTO WA_TVARVC.
    CLEAR WA_FILTER.
    SPLIT WA_TVARVC-LOW AT '-' INTO WA_FILTER-TABNAME WA_FILTER-FIELDNAME.
    CHECK SY-SUBRC = 0.

    COLLECT WA_FILTER INTO LT_FILTER.
  ENDLOOP.

  SORT LT_FILTER BY TABNAME.
  CLASS CL_ABAP_CHAR_UTILITIES DEFINITION LOAD.

* Get field offsets
  LOOP AT LT_FILTER INTO WA_FILTER.
    LS_TABNAME = WA_FILTER-TABNAME.

    IF LS_TABNAME NE LS_SAV_TABNAME.

      CALL FUNCTION 'DDIF_NAMETAB_GET'
        EXPORTING
          TABNAME   = LS_TABNAME
        TABLES
          DFIES_TAB = LT_DFIES
        EXCEPTIONS
          NOT_FOUND = 1
          OTHERS    = 2.

      IF SY-SUBRC <> 0.
        CONTINUE.
      ENDIF.

      SORT LT_DFIES BY TABNAME FIELDNAME.

    ENDIF.

    LS_SAV_TABNAME = LS_TABNAME.

    READ TABLE LT_DFIES INTO WA_DFIES
         WITH KEY TABNAME   = WA_FILTER-TABNAME
                  FIELDNAME = WA_FILTER-FIELDNAME
         BINARY SEARCH.

    CHECK SY-SUBRC = 0.

    WA_FILTER-POSITION = WA_DFIES-POSITION.
    WA_FILTER-OFFSET   = WA_DFIES-OFFSET / CL_ABAP_CHAR_UTILITIES=>CHARSIZE.
    WA_FILTER-LENG     = WA_DFIES-LENG.

    MODIFY LT_FILTER FROM WA_FILTER.

* Build segment name range
    IF SY-SUBRC = 0.
      WR_SEGNAM-SIGN   = 'I'.
      WR_SEGNAM-OPTION = 'EQ'.
      WR_SEGNAM-LOW    = WA_FILTER-TABNAME.
      COLLECT WR_SEGNAM INTO LR_SEGNAM.
    ENDIF.
  ENDLOOP.

* Loop at IDOC to clear fields
  LOOP AT IDOC_DATA ASSIGNING <FS>.
    IF <FS>-SEGNAM IN LR_SEGNAM.
      LOOP AT LT_FILTER INTO WA_FILTER WHERE TABNAME = <FS>-SEGNAM.
        CLEAR <FS>-SDATA+WA_FILTER-OFFSET(WA_FILTER-LENG).
      ENDLOOP.
    ENDIF.
  ENDLOOP.
ENDMETHOD.

I also added the following code to IF_EX_HRALE00OUTBOUND_IDOC~IDOC_DATA_FOR_RECEIVER_MODIFY:

* Clear IDOC fields
CALL METHOD ME->CLEAR_IDOC_FIELDS
  EXPORTING
     IDOC_CONTROL = IDOC_CONTROL
     RECEIVER     = RECEIVER
     MESTYP       = IDOC_CONTROL-MESTYP
  CHANGING
     IDOC_DATA    = IDOC_DATA.

Finally, I maintained the following TVARV variable:

That’s all it takes!  Now individual field values can be easily be filtered from outbound HRMD_A IDOCs!.

UPDATE: My colleague informed me that instead of using TVARV, I should continue to use BD53 to manage the IDOC reduction and change my code to look up the field reductions in TBD24.  This would be a great idea, but my full HRMD_A solution uses custom filter objects and a custom IDOC formatting function module.  And BD53 does not play well with these customizations.

This blog post describes how to receive an IDOC from an SAP system, using the SAP .Net Connector and Microsoft C#.

Introduction

The SAP .Net Connector simplifies creating C# programs that can interoperate with an SAP host. The SAP .Net Connector is available from the SAP Service Marketplace. You must have access to the SAP Service Marketplace to be able to download the SAP .Net Connector. The SAP .Net Connector must be installed on your development machine before we begin.

An IDOC is an Interface Document that is used to send or receive information to or from an SAP host.  An IDOC will consist of a header record and as many detail records as necessary. The header records follow the format of the EDI_DC40 table, and the detail records follow the format of the EDI_DD40 table. The exact format of the payload in the detail records depends on the type of IDOC being transmitted.

C# Code

We will create an application that displays the contents of IDOCs received from an SAP host. Use Visual Studio 2008 and create a new C# console application. Name the new application IdocReceive.

Add Reference to SAP .Net Connector.

In the Solution Explorer,  right-click on References and choose Add New Reference. Select both SAP.Connector.dll and SAP.Connector.Rfc.dll. Typically, these files will be found in C:\Program Files\SAP\SAP .Net Connector 2.0.

Our program will instantiate a custom class, IdocReceiver, that encapsulates the SAP transmit and receive logic.

IdocReceiver inherits from the SAP .Net Connector.  IdocReceiver overrides methods from the SAP .Net Connector to manage the flow of IDOCs from the SAP host. IdocReceiver also subscribes to two events exposed by the SAP .Net Connector that perform the actual transmission.

IDOC Receiver Main Method

Line 5 contains the reference to the SAP .Net Connector that we need.

The IdocReceiver object requires an SAPHost object that is used to configure the connection to the SAP Gateway. Line 9 instantiates the SAPHost object.

Line 14 calls the IdocReceiver constructor. The first parameter is the SAP Connection String, used to connect to the SAP host. There are three parts of an SAP Connection String:

-aProgramName is the program name as it is defined on the SAP Gateway. This value must match the Program ID configured on the SAP Gateway. Use SAP command SM59 to view the settings of the SAP Gateway.

-xSAPGWnn is the SAP Gateway number to which the IDOC receiver will register.  The SAP Gateway listens on a TCP/IP port number based on nn value. The actual port number is equal to 3300 plus the nn value. In this case nn is zero, so port 3300 is used.

-gHostName is the DNS host name of the SAP server. It is also possible to specify an IP address, like -g192.168.10.1.

Line 16 starts the SAP host, which makes it possible to begin receiving IDOCs. At this point, our program will now be visible to the SAP host, which you can verify using the Test Connection command via SAP transaction SM59. As long as the IdocReceiver object remains in scope, it will receive IDOCs.

IdocReceiver Class

To receive an IDOC, the IdocReceiver class inherits from the SAP .Net Connector SAPIdocReceiver class. To control the flow of IDOCs, the IdocReceiver class overrides certain methods of the SAPIdocReceiver class. To actually receive an IDOC, the IdocReceiver subscribes to two events exposed by the SAPIdocReceiver class.

Constructor

Here is the code for the IdocReceiver constructor.

IdocReceiver Constructor

On line 25 we declare our IdocReceiver and inherit from the appropriate SAP .Net Connector object. We use the StringWriter on Line 27 to store the contents of the actual IDOC received.

The constructor requires two parameters, the SAP Configuration string, and an SAPServerHost object that is a container for the IdocReceiver. Line 30 is where we call the base constructor.

The transfer of the IDOC raises an event at two times: when the transfer begins and when the transfer ends. On lines 32-33, we wire up our IdocReceiver methods to the BeginReceive and EndReceive events exposed by the SAPIdocReceiver class. Our IdocBeginReceive will be called at the start of the IDOC transmission, and our IdocEndReceive method will be called at the end of the IDOC transmission.

IDOC Flow Control

IDOCs flow out of an SAP system in a transactional way, in that an SAP host will send a particular IDOC once an only once. To accomplish this, the SAP host will put together one or more IDOCs into a transaction and send that off to the IdocReceiver that has registered on the SAP Gateway. The transaction is identified by a unique Transaction ID (TID) that is supplied by the SAP host. The SAP host will communicate with our IdocReceiver using the Transaction ID to control the flow of IDOCs from SAP to our program.

There are four methods of the base SAPIdocReceiver class that we need to override.

IDOC Flow Control Methods

In each case, the SAP host expects our code to return a zero if there are no difficulties. The TIDs passed as parameters can be used to verify the state of the transmission. This demonstration code leaves out any processing you may want to use to validate the state of the transaction.

The SAP host will first call the CheckTransaction method. If a zero is returned, the SAP host will call ConfrimTransaction. If a zero is then returned, the SAP host will begin transmitting IDOCs. When the transmission is complete, the SAP host will call CommitTransaction.

IDOC Reception

We use two methods to receive the actual IDOCs. At the start of the transmission, we assign a StringWriter to the EventArg, which tells the SAP .Net Connector where we want to place the payload of the transmission. When the transmission is complete, we can read from the StringWriter to extract the payload.

IDOC Reception

There can be one or more IDOCs transmitted at a time. Your code will need to parse the payload to determine what goes where.

If any of your code throws an exception, the SAP .Net Connector will detect that and alert the SAP side. The SAP side will then call your Rollback method.

Summary

Using the SAP .Net Connector makes it easy to receive an IDOC from an SAP host.

To learn more about IDOCs download the white paper: ALE & IDOC Leveraging