Limeade ONE Integration Guide
How do Cards Work with collectors?
Finalizing the Logical Port Configuration
Finalizing the Logical Port Configuration
Finalizing the Logical Port Configuration
Integration of Customer Workflows
Overview
Following is the list of systems integrations Limeade already offers.
Please note that Limeade is faster in integrating systems than documenting. If the details needed are not present in this document, feel free to contact Limeade with questions.
List of standard integrations:
- REST Webservices
- Sitrion Social
- Microsoft SQL
- Microsoft SharePoint
- Microsoft Office365
- SAP RFC
- SAP NW Gateway
- SAP HCM
- SAP ERP
- K2
List of custom integrations:
- Microsoft Exchange
- Microsoft Dynamics
- Microsoft PowerApps
- SAP Hana Cloud Platform
- Concur
- Ariba (on-premises)
- Peoplesoft
- Salesforce
Collectors
Collectors are a mechanism to move data from backend systems into the Limeade ONE Cloud to ensure that the clients can quickly retrieve and render Cards. Each Collector is optimized to work with a specific backend system and simply integrates with the Limeade ONE Cloud at the point of passing data into the Card API along with the identity of the associated card implementation.
How do Cards Work with Collectors?
|
|
|
|
Components:
Cards have always two components. The metadata from the Collector for a given backend system and the Card UI based on an AppBuilder Card project. If cards are using actions, usually a third component is included, the Connector to the given backend system.
Metadata from a Collector
Collector
A collector is a piece of software that usually gets installed in the backend system (e.g. SharePoint or SAP) or at someplace from where it can connect with the backend.
Metadata
Metadata is the data that is already in a well-formed format, which can be consumed by the Limeade ONE cloud.
Sample Metdata (JSON format):
Card UI
Card Project
The AppBuilder Card Project is the UI and translation layer of a Card
UI
The UI defines the look and feel of the card screens (summary and detail).
Translation
The translation of the incoming metadata is performed in the code-behind in a TranslateCard method. This also allows to manipulate data, enable push notifications and more.
Screen designer:
Translation of metadata to screen fields (Definition of header information, Push notification, …)
Mapping of metadata fields to screen fields
Component
Actions
Today Cards can have two different kind of actions a single action (Button) and a ConfirmAction. A single-action directly executes an assigned action, and a confirm action provides an upfront entry field for a simple string/text.
Connector
Actions are usually connecting back to a backend system like on approvals back to SharePoint or SAP. Therefore the Limeade ONE connectors can be used to define certain actions
Action Bar on a mobile device
Dataflow
This diagram should give a high-level overview of the overall card dataflow.
SAP
The Limeade ONE SAP workflow collector is an SAP program to send workflow decision steps out of SAP to the web service Limeade ONE hub. The collector core is designed to be run on all SAP Systems and not related to any SAP module-specific functionality. In standard shipment, the collector does not contain any workflow task-specific coding, the data evaluation will be the same for all task types.
Requirements:
- SAP ECC 6.0 EHP 4 at minimum
- Standard SAP workflow customization (transaction SWU3)
- Implemented and activated workflow(s) with "User Decision Step"
- Import of the Limeade ONE SAP collector transport (transport of copies) with objects in Limeade ONE's own APPS/ namespace
- Initial Configuration
- Installed Card Webservice
- (Optional) Schedule background job periodically to run our SAP Report /APPS/ONE_RUN periodically and push data into Limeade ONE
For the basic customizing, the following permissions are required:
SAP User
The SAP user is needed for configuration purposes
Customizing Authorization for Limeade ONE collector and SOA Manager
SM30, SM31, SOAMANAGER
(Optional) Setup Limeade ONE Collector as periodically background job
SP01, SM37
By default, the Limeade ONE collector retrieves the user decision step task description without specific details. To enrich the data that gets provided to the user, the following permissions are needed in addition:
SAP User
The SAP user is needed for implementation and configuration purposes
SAP Developer License Key
The key is needed to integrate custom workflow decision tasks through enhancement implementation
Developer Authorization at minimum access to transactions
- Debugging authorization
- SE38 to test Limeade ONE SAP Collector and enhancement implementation
- SE80 to implement the custom enhancements
- SE16, SE11 for testing and analysis purposes
General workflow authorizations for evaluation and analysis purposes
- SWDD, SWIA, SWI1
Initial Configuration
The initial configuration describes the major steps for a basic customizing of the SAP Collector.
Customizing
The following steps are describing the easiest possible customizing to check if the collector is working properly. Instead of using the tables directly, the program /APPS/ONE_IMG can be used as well for the customizing.
Define Connection Types
- Call transaction SM31 and enter /APPS/ONE_CON_TY in input field and choose maintain to define the connection types. Type W are supported by default.
- Create the entry as shown below
Define Connection Type Fields
- Call transaction SM31 and enter /APPS/ONE_CON_F in the input field and choose to maintain to define field for the connection types. The fields shown are obligatory; missing fields will lead to an exception.
- Create the entry as shown below
Connection Type Field Values
- Call transaction SM31 and enter /APPS/ONE_CON_FV in the input field and choose to maintain to define field values for the connection types. The field values shown are obligatory; missing fields will lead to an exception.
- Create the entry as shown below (adjust as needed)
If a LOG_PORT account is not yet created, please check the below steps, where the document describes how to create a logical port
Instance
- Call transaction SM31 and enter /APPS/ONE in the input field and choose to maintain to define an instance.
- Create a new entry as shown below and Save (change values as needed, especially Company ID and Company Password, both values can be found in the Get started section on http://one.sitrion.com )
Decisions
- Call transaction SM31 and enter /APPS/ONE_DEC in the input field and choose to maintain
- Create new entries, as shown, to define the decision alternatives (change and translate entries as needed, translations should be made for every workflow receiver language)
The entry without specifying a task ID will be used as a fallback in case no proper entry is found. An error only occurs in case no entry is found and no fallback is customized.
Users
- Call transaction SM31 and enter /APPS/ONE_USER in the input field and choose to maintain
- Create new entries if needed
If no entry is made, the User filter is excluded, which means, every user would get processed.
Tasks
- Call transaction SM31 and enter /APPS/ONE_TASK in the input field and choose to maintain
- Create a new entry as shown below and Save (change values as needed)
Logical Port (pre EHP6)
The following steps are showing the configuration for a logical port in SAP. This defines the connection between SAP and web services, which is built into the Hub. The logical port can be configured by using the transaction SOAMANAGER.
Helpful information around the SOAMANAGER can be found here:
Active Services in SICF
Configuring Web Services in SOA Manager
SOAMANAGER
After executing the transaction a browser window opens and shows the following screen. Use tab Application and Scenario Communication and choose Single Service Administration
Web Service Configuration
- Search by ConsumerProxy
- Search Pattern ICardService (case sensitive)
- Click Go
This should show the following entry:
Create Logical Port
Select the entry in the screen above and click Apply Selection. The area which is shown below appears, choose the Configurations tab and click Create Logical Port.
Logical Port Settings
- Define a logical port name (this name is the name, which is customized in the table /APPS/ONE_CON_FV, field LOG_PORT on connection type W)
- Enter a description of choice
- Provide the URL to the Hub web service. The URL will be similar to this: http://10.56.102.68:8095/CardService.svc?singleWsdl, however, the IP will have to be replaced with the user's IP or hostname.
Finalizing the Logical Port Configuration
Once the settings have been applied on the screen before, the configuration just has to be saved by clicking Save. Now, there is a new logical port, which has to be provided to the Limeade ONE customizing table /APPS/ONE_CON_FV, field LOG_PORT on connection type W.
Logical Port (EHP6 and EHP7)
The following steps are showing the configuration for a logical port in SAP. This defines the connection between SAP and web services, which is built into the Hub. The logical port can be configured by using the transaction SOAMANAGER.
Helpful information around the SOAMANAGER can be found here:
Active Services in SICF
Configuring Web Services in SOA Manager
SOAMANAGER
After executing the transaction, a browser window opens and shows the following screen. Use tab Service Administration and choose Web Service Configuration
Web Service Configuration
- Search by ConsumerProxy
- Search Pattern ICardService
- Click Go
This should show the following entry:
Configurations
By clicking the above-found entry, the user is forced to switch to the Configurations tab and Create a new Logical Port based on WSDL Based Configuration.
Logical Port Name
Define a logical port name (this name is the name that is customized in the table /APPS/ONE_CON_FV, field LOG_PORT on connection type W) and a description of choice.
WSDL Information
Provide the URL to the Hub web service. The URL will be similar to this: http://mycardwebserviceserver:8095/CardService.svc?singleWsdl, however, the IP will have to be replaced with the user's IP or hostname.
Finalizing the Logical Port Configuration
The following screens can just be confirmed with Next until reaching the HTTPSettings screen.
HTTP Settings
Please validate the computer name of access URL. This should be the hostname or IP of the machine where the web service is running.
Finalizing the Logical Port Configuration
The following screens can just be confirmed with Next until reaching the final screen, where users can confirm with Finish.
Usage
The collector will be started by using the SAP Report /APPS/ONE_RUN. This report is designed to be run as a periodical job in the background but can be used as a dialog report as well. It consists of two screens, the Selection Screen and the Result Screen if the option protocol was chosen.
Selection Screen
The following selection parameters are available:
- Test - With only the Test checkbox clicked, the program will run and execute all SAP checks. This will allow for the sending of the same messages repeatedly. It will not produce any output to the user and simulates running in the background.
- Protocol - Clicking only the Protocol checkbox will send any SAP data found to Limeade ONE Cloud on a per run basis.
- Create JSON Files - With the Test and Create JSON Files checkboxes checked, the program will run the same as having only the Test checkbox but will produce an ALV output that will display results of the run as well as allowing the user to see the JSON files produced that were sent to the Cloud. This would be used for initial development and troubleshooting.
Result Screen
A result screen only exists in case the selection parameter protocol was used. The protocol table shows details for every single item that was sent to the Limeade ONE hub and a description in the case that it was not sent. There is a single leading entry per instance followed by work item entries.
The description column shows possible exceptions. A detailed view of any entry in this column can be seen with a double click.
The JSON output column shows the JSON (if requested in the selection screen before) which gets returned from the web service on a successful call. With a double click on an entry in this column, the full JSON can be copied to a desktop. The JSON is quite helpful for creating Cards based on the given metadata in AppBuilder.
BAdI Enhancements
There are two BAdI's related to the collector. The most important one is the /APPS/ONE_BADI. Since this allows users to enhance the data, which is retrieved by default from the workflow with more relevant information, that could be needed beside the standard workflow information. The /APPS/ONE_SEND_BADI is currently implemented in the way that the outgoing communication goes through a web services call to the Hub.
/APPS/ONE_BADI
The BAdI /APPS/OS_BADI is implemented using enhancement spot /APPS/ONE_ENH_SPOT. This BAdI is used for general functions related to data retrieval. This BAdI can have multiple active implementations. To make sure the correct implementation is used, the BAdI will be instantiated using a Filtervalue the value is equal to the instance name defined in customizing (customizing table /APPS/ONE). There is a fallback implementation available which will be used in case no implementation is found for the instance name. This BAdI enables the customer to influence the data determination and creation of the XML structure. The available methods are described below. The BAdI is implemented in a way that it behaves like a persistent object. Lifetime starts with DETERMINE_ITEMS and ends after PROCESS_ITEMS. So it is possible to store information in BAdI class (custom implementation) for later use in the lifetime of an object.
CHANGE_ITEMS
This method is implemented in method DETERMINE_ITEMS of the class /APPS/CL_ONE after the standard data evaluation. The following parameters are available:
Name |
Type |
Description |
IS_CUSTOMIZING |
Importing |
contains the customizing entry for current instance |
IV_FROM |
Importing |
contains timestamp for begin of evaluation period for workitems |
IV_TO |
Importing |
contains timestamp for end of evaluation period for workitems |
IV_TASK |
Importing |
contains tasks which were considered for data evaluation |
CT_ITEMS |
Changing |
contains items which were determined |
The data determination timestamp stored in run history and used by the collector to evaluate items will not be changed, meaning that a long runtime may lead to a time gap. This is in the responsibility of a custom own implementation to consider this. The easiest way is to use the delivered timeframe (IV_FROM – IV_TO) instead of the current time for additional data evaluation to make sure that items not in this frame are considered at next runtime.
CHANGE_USERDETAILS
This method is implemented in the method GET_USER_DETAILS of the class /APPS/CL_ONE and will be called for each work item and its evaluated receivers.
Name |
Type |
Description |
IS_CUSTOMIZING |
Importing |
contains the customizing entry for current instance |
IS_WI_HEAD |
Importing |
contains work item head data the user information are related to |
CT_USERDETAILS |
Changing |
Contains the information for each user related to current workitem |
It can be used to change, delete or add information. In the case that the mail address for a user is not stored in the user detail data, the method can be used to add this information as it is needed for sending the notification. Another example is language. At the moment, only the mail address and the language (field langu_p and langup_iso in user details) are used.
CHANGE_DATA
This method is implemented in the method PROCESS_ITEM of the class /APPS/CL_ONE_SYNC. It is called after the evaluation of receivers and the basic data. The following parameters are available:
Name |
Type |
Description |
IS_CUSTOMIZING |
Importing |
contains the customizing entry for current instance |
IS_WI_HEAD |
Importing |
contains work item head data the notifications are based on |
CT_NOTIF |
Changing |
contains the determined notifications to be send |
This method will be called once for each WI determined. Remember that the BAdI class is persistent so it is possible to store data if a custom own implementation is created to minimize evaluation effort. The data is still available on next call, as long it happens in the same run of instance.
CREATE_XML
This method is implemented in the method PROCESS_ITEM after data determination and is responsible for XML creation. The program itself does not contain a XML conversion. The standard fallback class contains an implementation that can be copied in case a custom own implementation is used. Without copying no XML is created.
Name |
Type |
Description |
IT_DATA |
Importing |
Contains the evaluated data |
RV_XML |
Returning |
Contains the data as XML rawstring |
The XML will be created by using the transformation XSLT /APPS/ONE_DATA.
/APPS/ONE_SEND_BADI
BAdI /APPS/ONE_SEND_BADI is implemented using enhancement spot /APPS/ONE_ENH_SEND_SPOT. This BAdI enables the customer to influence how the data is sent. In standard, the information is sent by mail. The BAdI will be instantiated by using a filter. This Filter is the value of the related connection type (defined in /APPS/ONE_CON_TY and related to an instance by /APPS/ONE). Currently only W (Web Service) is supported. There is no fallback available. The BAdI is implemented in a way that it behaves like a persistent object. Lifetime starts at the beginning of PROCESS_ITEMS and ends at the end of PROCESS_ITEMS. So it will be possible to store information in the BAdI class for multiple uses in the lifetime of the object. This BAdI can have more than one active implementation so it is possible to send the gathered information to more than one system or in more than one way. As the customizing is not designed to consider this and the order of execution of each is unknown the history data for work items may contain invalid data and may affect the run history information as well. It is in the responsibility of the custom implementation to take care of this.
SEND_MESSAGE
Name |
Type |
Description |
IS_CUSTOMIZING |
Importing |
contains the customizing entry for the current instance |
IS_CONNECTION |
Importing |
contains the customizing entry for connection information related to the current instance |
IS_WI_HEAD |
Importing |
contains work item head data that the notifications are based on |
IV_TEST |
Importing |
A flag indicating if a program runs in test mode |
IV_SENDER |
Importing |
Contains the name of the user that is used for sending the data mail |
CS_XML |
Changing |
Contains content and information, in standard the time stamp for sending is changed and the success flag will be erased in case an error occurs |
Technical Details
Objects
Next to the report described in the usage section, the core functionality is located in the class /APPS/CL_ONE. It contains the following methods and attributes:
Method Name |
Description |
CONSTRUCTOR |
Initiates an object and reads values from customizing which are needed for data evaluation |
DETERMINE_ITEMS |
Determines the set of relevant work items to be processed |
CREATE_TIME_STAMP |
Returns a time stamp |
PROCESS_ITEMS |
Processes all items, there is no import parameter for items as they are stored local by DETERMINE_ITEMS |
SEND_MAIL |
Sends a mail, data is defined by import parameters |
SET_RUN_INFORMATION |
Sets runtime information about the current instance to table /APPS/ONE_RUN; needs to be called for every instance |
GET_WI_ITEMS |
Returns information about the processed items; can be used for protocol purposes |
GET_RUN_INFO |
Returns runtime information about the current instance |
SET_ELEMENT |
Adds information to the local element table, this table is used to build the XML |
PROCESS_ITEM |
Process a single work item and returns basic runtime data |
GET_WI_DETAILS |
Returns detail data for a work item |
GET_RECEIVERS |
Returns the receivers and their user details for a work item |
GET_CREATOR |
Returns the creator and its user details for a work item |
GET_USER_DETAILS |
Returns user details for a user |
GET_TEXTS |
Returns text related to a work item (decision information and work item description text) |
SET_DATA |
Sets the determined detail data to a local table |
SET_PROCESS_INFORMATION |
Set information about processed work items to database table /APPS/ONE_WI |
GET_DEFAULT_LANGUAGE |
Returns system default language |
GET_INSTALLED_LANGUAGE |
Returns list of languages installed in the current system |
In general, the public methods DETERMINE_ITEMS and PROCESS_ITEMS are covering all the needed information. SET_RUN_INFORMATION and SET_PROCESS_INFORMATION should be used also to ensure proper data evaluation. GET_WI_ITEMS and GET_RUN_INFO can be used to get information about every single item and general execution information. See report /APPS/ONE_RUN for example.
There are several other objects and setting which will be described high level below. There may be dependent elements not described here:
Name |
Type |
Description |
/APPS/CL_ONE |
Class |
Main class |
/APPS/CX_ONE |
Class |
Exception class |
/APPS/ONE_CL_BADI_FB |
Class |
Fallback class for badi implementation |
/APPS/ONE_CL_SEND_BADI_FB |
Class |
Fallback class for badi implementation |
/APPS/ONE |
Package |
Package for development |
/APPS/DTONE_SBAL_TEXT_01 |
Documentation |
Text used in exception classe |
/APPS/ONE_DO_CON_TYPE |
Domain |
Connection type |
/APPS/ONE_DO_DECISION_TYPE |
Domain |
Decistion type |
/APPS/ONE_DO_MAX_RETRY |
Domain |
Max retry count |
/APPS/ONE_DO_SEQNR |
Domain |
Sequence number |
/APPS/ONE_DO_WI_DESCRIPTION |
Domain |
Work item description text |
/APPS/ONE_DO_WI_STATUS |
Domain |
Work item status |
/APPS/SU_DO_DECISION_NUMBER |
Domain |
Decision ID |
/APPS/ONE_DS_ATT_NAME |
Data Element |
Attachment name of data attachment |
/APPS/ONE_DS_ATT_TYPE |
Data Element |
Attachment type of data attachment |
/APPS/ONE_DT_ACTIVE |
Data Element |
Active flag |
/APPS/ONE_DT_CON_SUBJECT |
Data Element |
Subject of mail |
/APPS/ONE_DT_CON_TYPE |
Data Element |
Type of connection |
/APPS/ONE_DT_DECISION_NUMBER |
Data Element |
Decision ID |
/APPS/ONE_DT_DECISION_TEXT |
Data Element |
Decision text |
/APPS/ONE_DT_DECISION_TYPE |
Data Element |
Decision Type |
/APPS/ONE_DT_DESCR_FLAG |
Data Element |
Description flag |
/APPS/ONE_DT_INCL_SUBST |
Data Element |
Substitutes flag |
/APPS/ONE_DT_INSTANCE_NAME |
Data Element |
Instance name |
/APPS/ONE_DT_MAX_RETRY |
Data Element |
Max retry count |
/APPS/ONE_DT_NEW_ONLY |
Data Element |
Only new items flag |
/APPS/ONE_DT_OVERWRITE |
Data Element |
Overwrite flag |
/APPS/ONE_DT_SEQNR |
Data Element |
Sequence number |
/APPS/ONE_DT_WI_DESCRIPTION |
Data Element |
Work item description text |
/APPS/ONE_DT_WI_STATUS |
Data Element |
Work item status |
/APPS/ONE_DT_WORKFLOW_ID |
Data Element |
Workflow ID |
/APPS/ONE_DT_WORKITEM_DESC |
Data Element |
Work item description |
/APPS/ONE_DT_START_DATE |
Data Element |
Start date |
/APPS/ONE_DT_START_TIME |
Data Element |
Start time |
/APPS/ONE_DT_END_DATE |
Data Element |
End date |
/APPS/ONE_DT_END_TIME |
Data Element |
End time |
/APPS/ONE_ENH_SEND_SPOT |
Enhancement Spot |
Enhancement spot for badi |
/APPS/ONE_ENH_SPOT |
Enhancement Spot |
Enhancement spot for badi |
/APPS/ONE |
Function Group |
Function group for table maintenance |
/APPS/ONE_CON |
Function Group |
Function group for table maintenance |
/APPS/ONE_DEC |
Function Group |
Function group for table maintenance |
/APPS/IF_ONE_CONSTANTS |
Interface |
Interface for constants used in SIAT/CL_ONE |
/APPS/ONE |
Message Class |
Message class |
/APPS/RUN_ONE |
Program |
Main program for ONE |
/APPS/ONE_CLEAN_UP |
Program |
Clean up report, mainly for testing purposes |
/APPS/ONE |
Table |
Leading customizing table |
/APPS/ONE_CON |
Table |
Customizing table defining the connection for instances |
/APPS/ONE_DEC |
Table |
Decision types |
/APPS/ONE_DECT |
Table |
Text table for decision types |
/APPS/ONE_DS_ATTACHMENT |
Structure |
|
/APPS/ONE_DS_DATA |
Structure |
|
/APPS/ONE_DS_XML |
Structure |
|
/APPS/ONE_DT_XML |
Table |
|
/APPS/ONE_RUN |
Table |
|
/APPS/ONE_TASK |
Table |
|
/APPS/ONE_USER |
Table |
|
/APPS/ONE_WI |
Table |
|
/APPS/ONE_TT_ATTACHMENT |
Table Type |
|
/APPS/ONE_TT_DATA |
Table Type |
|
/APPS/ONE_TT_TASK |
Table Type |
|
/APPS/ONE_TT_WI |
Table Type |
|
/APPS/ONE_TT_XML |
Table Type |
|
/APPS/ONE_DATA |
Transformation |
|
/APPS/ONE_CL_WS_BADI_FB |
Class |
BAdi Implementation for sending information by WebService |
Standard Data Determination
The following data will set in standard to a sent decision XML document:
Name |
Description |
ActionType |
Create, Delete |
CompanyId |
Limeade ONE company id |
CompanyPassword |
Limeade ONE company password |
EnvironmentName |
Limeade ONE environment |
MessageType |
Identifier for the type of message for Limeade ONE |
IndicatorAccept |
Identifier to send an “accept” |
IndicatorDecline |
Identifier to send a “reject/decline” |
Indicator… |
Further Identifiers |
@GENERICTEXT# |
Each line of the task description becomes @GENERICTEXT#001, @GENERICTEXT#002, … |
WorkflowId |
Id of the SAP workitem |
Subject |
Subject of the workitem |
EMailAddresses |
Approvers e-mail addresses |
Username |
Approvers SAP user names |
UserLanguage |
Approvers SAP user languages |
Tables - Data
The collector contains data tables used to store information about the history of runs and items. This information is needed as it is related to future executions.
/APPS/ONE_RUN - information about run
This table contains information about each run per instance.
Column |
Description |
MANDT |
Client of SAP System |
INSTANCE_NAME |
Name of instance the entry is related to |
TIMESTAMP |
Timestamp of data evaluation for this run |
HAS_ERROR |
Indicates if one or more items had errors |
/APPS/ONE_WI
This table contains information about each work item/notification sent, or to be sent. There can be more than one entry per work item. There will be one entry per Instance work item and run. The retry value will be increased for every run of related instance. If the max value is reached, this item will no longer evaluated by method DETERMINE_ITEMS.
Column |
Description |
MANDT |
Client of SAP System |
INSTANCE_NAME |
Name of instance the entry is related to |
WI_ID |
ID of related work item from SWWWIHEAD |
USERNAME |
User the work item is related to (receiver) |
DET_TIMESTAMP |
Timestamp of evaluation of data |
SEND_TIMESTAMP |
Timestamp of sending this item (or at least the try to) |
RETRY |
Number of tries since initial run |
STATUS |
Result of run ERR-erroneous SUC-successful |
DESCRIPTION |
Description of issues occurred |
Tables - Customizing
The collector uses several customizing tables described in the following chapters. All relevant tables do have a maintenance view with the same name as the table itself.
/APPS/ONE
This is the main customizing table to define the different instances. Technically an instance is just an identifier used to customize values, tasks and users used during runtime. Each active instance will be considered during a run. Some of the values contained in customizing are not considered in base implementation e.g. start & end. It’s up to the implementation of the enhancements to use these.
Name |
Description |
MANDT |
Client of SAP System |
INSTANCE_NAME |
Name of instance |
CON_TYPE |
Defines the type of data that is sent |
TEMPLATE_ID |
Type this is an ID used to identify the related process in Limeade ONE and is part of the notification message |
INCL_SUBST |
Flag if substitutes should be considered as receivers |
ACTIVE |
Flag if this instance is active |
OVERWRITE |
Indicates that the start and end of the appointment (if there are these dates) should be overwritten by the defaults defined in start/end date/time column of this table |
MAX_RETRY |
Defines the max number of retries |
WITH_DESCRIPTION |
Defines if the description of the work item is to be included in data |
/APPS/ONE_CON_TY
This table defines the connection types. A connection type is the starting point to define a new way of sending the data. Mail and Web Service are defined in the standard.
Name |
Description |
MANDT |
Client of SAP System |
CON_TYPE |
ID of connection type |
/APPS/ONE_CON_TT
This table defines language-dependent texts for connection types.
Name |
Description |
MANDT |
Client of SAP System |
LANGU |
Language key |
CON_TYPE |
ID of connection type |
CON_TEXT |
Description of the connection type |
/APPS/ONE_CON_F
This table defines the available fields per connection type. Each field defines a property that is used by a connection type.
Name |
Description |
MANDT |
Client of SAP System |
FIELD |
ID of field |
/APPS/ONE_CON_FT
This table defines the language-dependent field description.
Name |
Description |
MANDT |
Client of SAP System |
LANGU |
Language key |
FIELD |
ID of field |
/APPS/ONE_CON_FV
This table defines the language-dependent field description.
Name |
Description |
MANDT |
Client of SAP System |
CON_TYPE |
Connection type |
FIELD |
ID of field |
FIELD_VALUE |
Value for field ID |
/APPS/ONE_DEC
This customizing table defines the decision alternatives for the possible decisions ACCEPT, REJECT and OTHER. This is related to a task ID. In the case that there is no task ID, the entry defined will be used as a fallback. This table has a related text table /APPS/ONE_DECT for the language-dependent text of the decision.
Name |
Description |
MANDT |
Client of SAP System |
TASKID |
ID of the related task |
DECISION_TYPE |
Type of decision ACCEPT; REJECT, OTHER |
DECISION_NUMBER |
Number of decision |
/APPS/ONE_TASK
This table is used to define which task should be used for data evaluation for related instance. If this table is left blank for an instance all tasks will considered.
Column |
Description |
MANDT |
Client of SAP System |
INSTANCE_NAME |
Name of instance the entry is related to |
TASK |
Workflow Task ID to be considered for instance defined by instance_name |
WORKFLOW |
Can be used to define the workflow containing the task (not used at the moment) |
NEW_ONLY |
Flag if only new entries should be used for data determination new = status “READY” (not used at the moment) |
WI_DESCRIPTION |
Description field |
/APPS/ONE_USER
This table contains users or ranges of users to be excluded from the result. It is built like a selection structure to be able to define ranges.
Column |
Description |
MANDT |
Client of SAP System |
INSTANCE_NAME |
Name of instance the entry is related to |
SEQ_NR |
Sequence number |
SEL_SIGN |
Selection sign - refer to SAP standard help for more details |
SEL_OPTION |
Selection option - refer to SAP standard help for more details |
SEL_LOW |
Low value - refer to SAP standard help for more details |
SEL_HIGH |
High value - refer to SAP standard help for more details |
Exception Handling
For this program, the exception handling is used to handle and report errors and issues. The exception class /APPS/CX_ONE was implemented for this. Errors can be found in the application log (TA SLG1) and in the history tables mentioned above. For the application log, a new object /APPS/ONE_LOG was created. To get information about run and item information the methods GET_RUN_INFO and GET_WI_ITEMS of the class /APPS/CL_ONE can be used after execution.
Integration of Customer Workflows
As described in the configuration expects a setup which workflow user decision step has to be pushed. Doing this registers the decision tasks for the Limeade ONE collector. Since each workflow is custom there is a need to implement an enhancement through explicit Enhancement Spots on an SAP system to read the related workflow data. This implementation will be held in custom namespace mostly Z* or Y*.
Example:
The BAdI Enhancement spot /APPS/ONE_ENH_SPOT ONE gets enhanced though custom implementation class ZCL_BADI_IMPL_ONE_BANF
The call implements the interface method /APPS/ONE_IF_BADI~CHANGE_DATA where each decision task has to be processed so be able to be consumed by Limeade ONE.
Method parameters:
Example of Purchase Requisition Task integration:
* Purchase requisition decision task
IF iv_wi_head-wi_rh_task EQ 'TS99200002'.
" get related objects to work item - need to evaluate banf number
CALL FUNCTION 'SAP_WAPI_GET_OBJECTS'
EXPORTING
workitem_id = iv_wi_head-wi_chckwi
language = sy-langu
TABLES
objects_2 = lt_objects.
READ TABLE lt_objects INTO ls_object WITH KEY typeid = 'BUS2105' catid = 'BO'.
IF sy-subrc EQ 0.
lv_banfnr = ls_object-instid.
ENDIF.
CHECK lv_banfnr IS NOT INITIAL.
" read related purchase requisition data
CALL FUNCTION 'BAPI_REQUISITION_GETDETAIL'
EXPORTING
number = lv_banfnr
account_assignment = 'X'
item_texts = 'X'
services = 'X'
service_texts = 'X'
TABLES
requisition_items = requisition_items
requisition_account_assignment = requisition_account_assignment
requisition_text = requisition_text
requisition_limits = requisition_limits
requisition_contract_limits = requisition_contract_limits
requisition_services = requisition_services
requisition_services_texts = requisition_services_texts
requisition_srv_accass_values = requisition_srv_accass_values
* convert SAP data to ONE à ct_data[]
"Purchase Requisition ID
ls_data-order_no = lv_ordernr.
ls_data-key = 'BANFNR'.
CONCATENATE '<![CDATA[' lv_banfnr ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"evaluate all related items
LOOP AT requisition_items ASSIGNING <ls_requisition_items>.
ls_data-order_no = lv_ordernr.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_CREATED_BY' INTO ls_data-key.
CONCATENATE '<![CDATA[' <ls_requisition_items>-created_by ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"Product
ls_data-order_no = lv_ordernr.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_ARTICLE' INTO ls_data-key.
CONCATENATE '<![CDATA[' <ls_requisition_items>-short_text ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"Quantity
ls_data-order_no = lv_ordernr.
lv_tmp_string = <ls_requisition_items>-quantity.
CONDENSE lv_tmp_string.
lv_quantity = <ls_requisition_items>-quantity.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_QUANTITY' INTO ls_data-key.
CONCATENATE '<![CDATA[' lv_tmp_string ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
* "UNIT
ls_data-order_no = lv_ordernr.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_UNIT' INTO ls_data-key.
CONCATENATE '<![CDATA[' <ls_requisition_items>-unit ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"PRICE
ls_data-order_no = lv_ordernr.
lv_tmp_string = <ls_requisition_items>-c_amt_bapi.
CONDENSE lv_tmp_string.
lv_price = <ls_requisition_items>-c_amt_bapi.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_PRICE' INTO ls_data-key.
CONCATENATE '<![CDATA[' lv_tmp_string ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"PRICE per UNIT
ls_data-order_no = lv_ordernr.
lv_tmp_string = <ls_requisition_items>-price_unit.
CONDENSE lv_tmp_string.
lv_price_unit = <ls_requisition_items>-price_unit.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_PRICE_UNIT' INTO ls_data-key.
CONCATENATE '<![CDATA[' lv_tmp_string ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"CURRENCY
ls_data-order_no = lv_ordernr.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_CURRENCY' INTO ls_data-key.
CONCATENATE '<![CDATA[' <ls_requisition_items>-currency ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
"Position sum
lv_pos_sum = lv_price * lv_quantity.
ls_data-order_no = lv_ordernr.
lv_tmp_string = lv_pos_sum.
CONDENSE lv_tmp_string.
CONCATENATE 'ITEM_' <ls_requisition_items>-preq_item '_POS_SUM' INTO ls_data-key.
CONCATENATE '<![CDATA[' lv_tmp_string ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
lv_ges_sum = lv_ges_sum + lv_pos_sum.
ENDLOOP.
"total sum evaluation
ls_data-order_no = lv_ordernr.
lv_tmp_string = lv_ges_sum.
ls_data-key = 'ITEM_TOTAL_SUM'.
CONCATENATE '<![CDATA[' lv_tmp_string ']]>' INTO ls_data-value.
APPEND ls_data TO ct_data.
CLEAR ls_data.
lv_ordernr = lv_ordernr + 1.
ENDIF. "decision task end
Microsoft SharePoint
The SharePoint collector can be used to listen on SharePoint lists, document libraries or task list. The collector itself gets deployed as a SharePoint solution package (WSP).
The deployment of the WSP can be executed by using the following PowerShell statements:
Add Solution to SharePoint
Add-SPSolution -LiteralPath C:\temp\Sitrion.ONE.SharePoint.wsp
Deploy the solution
Install-SPSolution -Identity Sitrion.ONE.SharePoint.wsp -GACDeployment
Activate needed features
Install-SPFeature -path Sitrion.ONE.SharePoint_ONEInstaller\Feature.xml
Install-SPFeature -path Sitrion.ONE.SharePoint_CardPublisherSite\Feature.xml
Install-SPFeature -path Sitrion.ONE.SharePoint_CardPublisherFarm\Feature.xml
Once the deployment has been executed, the initial configuration can be done.
Through the deployment, there is the ability to create a new Service Application called Sitrion ONE Service
Once the service application has been created, configure the Limeade ONE tenant settings - mainly the Company Password and Company-ID.
Both values can be found on the Get Started section on http://one.sitrion.com.
The environment is by default: https://one.sitrion.com should there be a case that the SharePoint environment can't connect straight to the Cloud, use the Limeade Card Webservice as a bridge/proxy between the OnPrem environment and the Cloud.
When this one-time configuration has been saved, go ahead and configure the lists desired to use for the SharePoint collector.
The list itself can be configured by using the Limeade ONE Card Publisher Settings in the given Site Settings, where the list itself is located (should the Limeade ONE Card Publisher Settings not be available here, please check if the Site Collection Feature for the Limeade ONE collector, Limeade ONE Card Publisher, is active).
If no lists have been configured yet, the following screen - where a New Connection can be created - will show.
In connection settings:
- Select a SharePoint List
- Define the events on which the collector should be executed
- Define the Message Type (the Message Type is the identifier for the Card to be built with the AppBuilder)
- Select the needed columns and Save the selection
From now, every time something is modified in the list, the Limeade ONE collector gets executed on the given event and sends the data directly to the Limeade ONE cloud.
The cloud itself will check if a Card is available for the metadata, for the given MessageType that was just sent. If a card is available, it'll execute the Translate method in the card and will provide the card to the given users.
When a connection has been saved, it can be modified by using the Edit button and will also have the option to Generate Sample Data. The sample data is helpful when building the Card in the AppBuilder.
Custom Collector
The cloud has its own Card API, which allows users to connect from certain backend systems.
Cards have basically two components.
The first one is the UI which gets designed by using the AppBuilder.
The second component is the backend data. The handling on cards is different than it is for micro-apps. Micro-apps are pulling data from a backend system while Cards get data pushed from a backend. For cards, Limeade ONE is using a Card API in the cloud. The Card API is based on a REST endpoint.
The endpoint URL is https://one.sitrion.com/api/v2/cardpublisher/write which requires a company ID and a customer secret for authentication. The card data is provided within a card routing object as JSON.
The web request needs two header objects for authentication:
Authorization = “sitauth ”+CompanyPassword as Base64
Sample: If company password is MyCompanySecret, the header would be
Authorization = sitauth TXlDb21wYW55U2VjcmV0
sitrion-companyId = CompanyId as string
Sample: If my company id is FEA28DF4-3B31-489B-AE7A-43B5B19CE878, the header would be
sitrion-companyId = fea28df4-3b31-489b-ae7a-43b5b19ce878)
The body needs to contain the card routing object as JSON:
{
"Actor": {
"DisplayName": "John Doe",
"Email": "john.doe@sitrion.com"
},
"SendTo": [
{
"DisplayName": "Jane Doe",
"Email": "jane.doe@sitrion.com"
}
],
"CardId": "31483b47-2b27-459e-8da4-5c0936534f3a",
"MessageType": "MyCard",
"ActionType": 1,
"Data": {
"PurchaseOrderId": "123456789",
"Title": "New Purchase Order"
},
"CardDate": "2015-05-26T13:31:21.2383418Z"
}
ActionType = 0=None, 1=Create, 2=Update, 3=Delete- Initially, a card has to be created. With the card ID other actions can also be executed on the same card
- CardDate - The date-time that shows up in the header of a card (recommend UTC time)
- CardId - This needs to be a unique id for the card; this ID can be used later for card actions like Delete or Update
- MessageType - This is the identifier between the metadata being sent here and the card UI, which has to be built with the AppBuilder
- Actor - This is displayed in the card header, as the person who sent the card. If the Email property matches a Limeade ONE user, the profile picture on the card will be retrieved based on this
- SendTo - With SendTo, users can define the Limeade ONE users that should receive this card. If SendTo is kept empty, everyone who has assigned this card in a role will receive the card
- Data - Data is a simple dictionary that can be prefilled with the data that would be needed on a card
A sample solution based on .NET code in the GitHub repository. This also contains a JSON sample incl. a JSON schema.
Microsoft Office365
The Microsoft Office 365 collector works similarly to the SharePoint collector. Based on the fact that it's running on Office 365, instead of deploying it manually it can be retrieved the collector from the Office 365 store.
Card Webservice
Collectors are usually connecting directly to the card REST web service in the Cloud. In some infrastructures, this might not be always feasible. Based on this an on-premise web service can be installed, that can talk to the Cloud web service. The Card Webservice is a SOAP and REST-based web service that can be used as a kind of relay between the on-premise world and the Limeade ONE cloud. The Card Webservice often gets installed on the same machine where the Hub is installed because that machine has already outbound connectivity to the Cloud.
The internal system (e.g. SharePoint, SAP) can now connect to the Card Webservice, which is installed internally, and the Card Webservice simply passed the data through to the Cloud.
One example where this is used is the SAP collector. SAP doesn't connect directly to the internet in most cases and often doesn't allow connection to REST services, like the Limeade ONE card service, in the cloud it is built for. The Card Webservice, in this case, takes an XML extract from SAP and converts it into JSON to pass it to the Cloud's REST endpoint.
The other example is when a SharePoint isn't allowed to connect straight to the internet, a user can simply use the build in the REST webservice of this Card Webservice as the internal proxy. The REST endpoint of the Card Webservice simply passes the incoming JSON to the Cloud's REST endpoint.
The Card Webservice (Collector Proxy) can be downloaded in the Get Started section of the admin portal on http://one.sitrion.com.
Prerequisites
To install the Card Webservice, please make sure that the machine where the Card Webservice has the following prerequisites:
Operating System
Windows 10, Windows 7 Service Pack 1, Windows 8, Windows 8.1, Windows Server 2008 R2 SP1, Windows Server 2012, Windows Server 2012 R2
.NET Framework 4.6 (Full Installation)
Installed Internet Information Server (IIS) role incl. ASP.NET and WCF Activation Features
Connectivity
The Card Webservices requires outbound access on HTTP port 443.
Since the Cloud is hosted on Microsoft Azure Datacenters, Limeade suggests opening these ports on the machine where the Card Webservice is installed for any IP. Should there be a need to target only specific IP's, Microsoft offers the Windows Azure Datacenter IP Ranges here: http://msdn.microsoft.com/en-us/library/azure/dn175718.aspx
Limeade ONE is currently hosted in the following Azure datacenters:
- West US (California)
- West Europe (Netherlands)
Hardware
The Card Webservice is a lightweight component. Based on this, the hardware requirements for the Card Webservice are corresponding to the given operating system and installed features (e.g. NET Framework).
As a suggestion we give the following requirements:
Minimum:
- Single CPU with minimum of two cores
- 4 GB RAM
- 10 GB free disk space
Recommended:
- 2 CPU's (each with a minimum of 2 cores)
- 8 GB RAM
- 10 GB free disk space
Of course, the Card Webservice can run also in a virtualized environment.
Install the Card Webservice
The following screen shows the Setup program of the Card Webservice
Click Next to continue.
Destination Folder
Choose the folder for the Card Webservice to be installed in.
Click Next to continue.
User Settings
Configure the user for the Application Pool. If not changed, it will install with the Network Service account on the installed machine.
Click Next to continue.
Website Settings
Configure the Website Name and the port which is used in the IIS for the Card Webservice.
Click Next to continue.
Company ID/Shared Key/Environment Name
The Company ID and Shared Key are the identifiers of a tenant. A company ID can be retrieved on http://one.sitrion.com.
The environment name should by default target to https://one.sitrion.com.
Ready to install
Click Install to start the installation of the Card Webservice on the machine.
Finish
The Card Webservice is now installed.
Click Finish to exit the setup.
Validate
To validate if the card web service is hosted, check if the WSDL is accessible.
The service should be accessed via the following URL if the default settings were used: http://localhost:8095/CardService.svc?singleWsdl
ocalhost:8095 may have to be adjusted to the corresponding name and port.
The REST endpoint of the web service is hosted straight on the base URL, which would be in the default installation http://localhost:8095. Reflecting this, for example, for the SharePoint collector: Instead of using https://one.sitrion.com as the environment name, http://mycardwebservicemachine:8095 would be configured (where mycardwebservicemachine is the name of the place where the Card was installed on the webservice, and of course, the corresponding port).
Proxy Configuration
The proxy configuration itself needs to be configured manually in the config file of the Card Webservice. The config file is by default located in the folder C:\Program Files\Sitrion\Sitrion ONE Card Webservice\Web.config. The file itself is a default .NET configuration file where a proxy can be configured with .NET defaults like described in this MSDN article.
Connectors
Connectors are used for integrating micro-apps with specific backend systems such as SAP, SharePoint or REST services. They have a design-time and run-time component. At design-time, a connector can be used in the AppBuilder to browse backend system elements and types. Micro-apps use connectors at runtime for sending or receiving data from these systems.
The connector can also be used on Cards, to integrate card actions (e.g. approve/reject on approvals cards) with backend systems.
SmartRoutines
For SmartRoutines, Limeade provides two different types of Connectors:
- SmartRoutines (SAP NW Gateway) - Connects through SAP NetWeaver Gateway to SmartRoutines SAP models
- SmartRoutines (SAP RFC) - Connects through SAP RFC to SmartRoutines SAP models
The SmartRoutines connectors give you the capability to connect to our SmartRoutines communication layer which can be based on the given connection types (RFC/Gateway). SmartRoutines uses a proven mechanism to connect directly to ABAP objects through this connectivity layers.
Custom Service
In addition to using pre-defined connectors, custom code can also be used inside of a Card or micro-app.
Custom Code can be added manually or by using the Data & Actions option Add Data Source > Select Custom Service as a Datasource.
For both ways, manually or by using the wizard, a class will be preferably in the Services or DataTypes folder, which uses the attribute OneService to get recognized by the designer.
The same goes for custom datatypes, they also can be coded. It's required to use the DataContract and DataMember attribute above the given class and property definition.
Microsoft SharePoint
The SharePoint connector allows users to consume on-premise SharePoint lists and document libraries from their SharePoint 2010/2013 environments.
Note on SharePoint Online Connectivity
The connector also allows SharePoint Online connectivity. For SharePoint Online, please make sure that the SharePoint Server 2013 Client Components SDK has been installed on the machine where the Limeade ONE Hub is installed, and on the machine where the AppBuilder is installed.
Video Tutorial
Limeade ONE - Read Data from SharePoint
REST
The REST connector allows access to on-premises RESTful services based incl. security like Username/Password or Anonymous Authentication.
Video Tutorial
Limeade ONE - Connecting to a REST service
SAP RFC
The SAP RFC connector allows users to connect through the RFC connection layer to an on-premise SAP system.
The SAP RFC connectivity is performed through SAP's librfc32.dll.
To use the SAP RFC connector, make sure that the hub and also the machine where the AppBuilder is used has this dll's in place.
LibRfc32 Installation on a 32 Bit OS
- Copy the LibRfc32.dll (32 Bit Version, also installed when you install SAP GUI/SAP Logon) into the C:\Windows\System32 folder.
LibRfc32 Installation on a 64 Bit OS
- Copy the LibRfc32.dll (64 Bit Version, Download via SAP SDN) into the C:\Windows\System32 Folder.
- Copy the LibRfc32.dll (32 Bit Version, also installed when you install SAP GUI/SAP Logon) into the C:\Windows\SysWOW64 folder (this Folder means System Windows on Windows 64)
The LibRfc32 requires the Visual C++ 2005 Runtime. Please make sure this is installed on the given machine.
RFC (BAPI)
RFC's can be accessed through these connectors. The only requirement is, that the given function modules have the processing type marked as a Remote-Enabled Module in SAP.
Tables
SAP tables can also be accessed through the connector (read-only). Since tables are by default not accessible from outside SAP, internally the standard SAP RFC RFC_READ_TABLE supports the connector to consume SAP tables.
Video Tutorial
Limeade ONE - Read data from a SAP RFC
Extensibility
Limeade ONE is built for extensibility, so if a Connector or Collector has not been found for the backend system, please contact Limeade.
Comments
0 comments
Article is closed for comments.