• Home
• ››Archived Documentation
• ››InterConnect

 

Workflow API for InterConnect

---

First published on: 11/13/2023/10:17 pm

 

 

The Workflow API for InterConnect provides details on how to configure Workflows for asynchronous access to SAP Business One data. The element definitions below provide an overview of valid syntax for configuring workflows that meet your specific business requirements.

 

Key Elements

 

Sample Usage

This example shows the structure of a Workflow that polls a folder location (C:/uploads/orders/) for XML files, and then processes and loads the processed order into SAP Business One as a new oOrders object. For an in-depth example, see Example: Processing an order from a third-party system.

 

 

 

Workflow Element

Workflow is the root element that defines the workflow details. This can be configured to use standard sources and actions, or it can be configured to use customized sources and actions.

 

 

Workflow Attributes

RequireCompany - Boolean to identify if the workflow will require a DI-API company. This value defaults to true so it is optional. Would normally be used if you have actions that just run queries etc. and non-transactional actions.

 

Trace - [On|Off|OnError] - Use this attribute to troubleshoot or log additional information about the workflow objects and actions as they are processing. The default value is OnError which will log all Exceptions. Set the value to On to trace all debug information that is output from actions and message source objects. Off is not recommended, and can be used to disable logging entirely.

 

For production systems, Trace=OnError is the recommended setting to avoid excessive log files from being created.

 

 

Actions Element

This is the starting element containing one or more actions that will be executed as part of the workflow integration.

 

Base Attributes

Attribute	Description
RelatedInfoNode	When this attribute is specified the result of the action (if it is valid XML) is appended to the message being processed in a separate XML section called . For example, this could be used to retrieve customer information from a system like Magento while processing sales orders. This customer information would then be available to process via XSLT.
TransformXSLT	This attribute specifies an XSLT that will be applied to the message that is being processed by the Action.
TransformRoot	(optional) This attribute is used when the TransformXSLT is specified. It is an optional value to instruct the XSLT transform to begin at a specific XElement instead of the document root.
CopyToFolder	(optional) Name of message folder to use after successful processing of the new message in the queue. Leave this attribute empty if you only want messages created upon failure. This creates a copy of the message at the time of processing and saves it.
ExceptionFolder	Name of message folder to use when creating the new message in the queue upon failure. This creates a copy of the message at the time of processing and saves it.

 

Child Elements

contain sub-elements , as shown in the code sample below. 

• This allows you to define a parameter value that will be passed into the executing action.
  • Name - Name of the parameter.
  • ElementName - (optional) Optionally set the starting XML element to select your comparison XPath. For example, set this value to RelatedInformation and all XPaths will be executed against that node.
  • ParameterXpath - XPath into the value of parameter.

 

 

This type of action is used to execute a B1WebAPI query against the Business One database and return values to the workflow processor. The B1Query is typically used to populate the element of a Message being processed with extra parameters or details.

 

In the example below the results from executing the DoesMagentoBPExist query via the B1WebAPI will be added to a node called B1BPLookup and appended to the Related Information element.

 

 

 

Attributes for B1Query Actions

• QueryName - The name of the query to execute inside the SAP Business One system via a call to the B1WebAPI. Results will be returned in standard B1WebAPI XML Format.
• QueryCategory - The name of the B1WebAPI category that contains the query specified in the QueryName attribute. Defaults to B1WebAPI.

 

 

For example:

 

This type of action is used to create a transactional object inside the SAP Business One system via XML from either a message or a previous action.

 

 

Attributes for B1Object Actions

• B1KeyXpath - XPath to the b1 internal key that can be stored in a message.
• Method - Insert/update.
• B1ObjectType - Specifies the object type to create for the action.
• HaltOnFail - [true|false] (optional) Boolean that specifies whether or not to keep processing upon failure.

 

 

For example:

 

This type of action is used to store a message into the message queue table.

 

 

 

Attributes for PersistMessage Actions

• SuccessFolder - Name of the message folder to use upon success when creating the new message in the queue. Leave this attribute empty if you only want messages created upon failure.
• ExceptionFolder - Name of message folder to use upon failure when creating the new message in the queue.
• MessageType - Type of the message to create in the system queue.

 

Custom Message Actions

The workflow framework supports the ability to write your own custom message actions to implement logic that is specific to your solution.

 

In order to complete the configuration of your custom message actions you will need to populate the CustomWorkFlowClass section of the workflow service B1WorkFlowService.config file. You will also have to make sure you custom dll is in the bin directory of the service.

 

This is an example of how that was done for Magento:

 

 

In order to create a custom message action your class needs to implement one of the following classes. Each class has several methods that must be overridden, which can be identified in your code using Intellisense.

 

There are three options to inherit from when creating a custom action, as outlined below.

 

Custom Action Inheritable Classes

 

Class	Description
B1Object	Use this class as your base class when you will be creating a B1 document. Ex: SPS Order Action.   If you plan on creating the objects directly via B1WebAPI or DIAPI then don't use this object.   Example code that can be executed via a custom action that inherits from B1Object: result.B1ObjectKey = base.ProcessMessage(message, variables, workFlowBatchID, branchName);
BaseSender	Use this class as your base class when you require the full XML of a B1Object. If your message contains a b1object key and type base sender will auto load the object XML into your custom action. If you do not require the full object XML it is not required to use this class.
BaseAction	Use this class as your base class when the other two options are not applicable. This is the base action class that all workflow actions will use. There are some base methods you will need to implement to use this class and you write your custom code in those methods.

 

Message XML Envelope

All InterConnect projects involve working with message XML generated by the SAP Business One system or the integrated external system. To improve the readability and consistency of our message XML a standard envelope will wrap the information that it contains. For more details, see XML Envelope Format for InterConnect.

 

Branches Element

This is the starting element containing one or more branches that will be executed as part of the workflow integration. Each Branch defines a stage of execution for the workflow.

 

This element is the basic workflow building block that enables you to group together other branches and actions. If no type is specified it will just pass the message from the message source to the child branches/actions contained within.

 

 

Attributes

• Name - Name describing the branch.
• Type - Identifies the type of branch being used in the workflow section.
• B1TransactionType - (optional) If this optional parameter is specified, then the workflow will only execute actions inside of the Branch if the transaction type equals the value specified. This is normally used with the WorkFlowEvent messages to trigger specific logic for adds vs updates.
• SplitterXPath - (not yet implemented - optional) This defines the XPath into XML that will be used to split the data. This is an optional parameter that creates multiple messages from a message passed to the branch. Typically a splitter is used to break a large XML message into smaller transactional elements based on the specified XPath.

 

This element is a special kind of branch that allows for conditional checks to be performed before deciding which branches/actions to complete. The example below checks the existence of a BP record before requesting the information from Magento and creating a new Business Partner.

 

 

 

Attributes for Conditional Branches

• TestValue - Defines the comparison value.
• ElementName - (optional) Set the starting XML element to simplify your comparison XPath. For example, set this value to RelatedInformation and all XPaths will be executed against that node.
• ComparisonXpath - Defines the XPath to the value inside the message XML for comparison with test value.

 

Header Element

Header defines the metadata about the workflow including details such as the workflow name and description.

 

Example

• Name - A brief name of the workflow processor.
• Description - An optional description of the workflow processor.

• Settings - This element consists of optional global constant information that can be accessed during the branches/actions of the workflow. For example: Web service URL. Setting contains the following attributes:

  • Name - Name assigned to the setting.
  • Type - Identifying type of the setting, such as string, datetime, int, etc.
  • Value - Value of the specified setting.

 

MessageSource Element

This element enables users to request messages from a resource and bring them into the workflow processor. The result of a message source is always one or more messages that can be processed by some of the action types.

 

Base Attributes

Attribute	Definition
BatchSize	(optional) The number of messages to pull into the workflow in a single batch.
ConfigurationName	(optional)   The name of the configuration section defined in the XML workflow configuration file. The message source will be passed the configuration XML information when it is executed by the workflow engine. Configuration files will be loaded from any XML file found in the Workflow Portal's /service/Config/ folder. As such, every config file should have a unique root node (or multiple root-level nodes). For example, the file /service/Config/magentoConfig.xml contains the following content.   To reference this config, set the ConfigurationName to match the root node, in this case ConfigurationName=TestMagento.   http://www.myonlinestore.com/api/index/ soapUser soapPassword 1 base false C20000 1 EX
CreateMessages	(optional) [true|false] Specifies whether or not to create messages for this MessageSource. This can be used to disable a MessageSource without deleting it (false). Defaults to true.
DefaultFailFolder	(optional) Specifies the default folder to use for storing messages that have failed to be processed.
Name	(optional) The unique name assigned to the branch. This property is not serialized. Used for readability.
SaveFirst	(optional) [true|false] Default is false. If set to true, this will save the workflow messages to the database before applying actions.
SplitterXPath	(optional) Contains the node name of the elements we wish to retrieve from the message source. This is an optional parameter that creates multiple messages from the data returned by the message source. Typically, a splitter is used to break a large XML message into smaller transactional elements based on the specified node name. This field name may change in future versions, as it’s not actually an XPath.
SuccessFolder	(optional) Specifies the workflow folder to use for storing successfully processed messages.
Type	(required) Specifies the type, which will determine the behavior of the MessageSource. Supported and planned message source types are: MessageSource Type: "Message" MessageSource Type: "HTTPRequest" - Not yet implemented MessageSource Type: "HTTPPost" - Not yet implemented MessageSource Types: "FTP", "FTPCSVFile", "FTPXmlFile" MessageSource Type: "SFTPCSVFile", "SFTPXmlFile" Custom MessageSource Types
WebMethod	(optional) Used in message source objects such as Magento Connector or custom objects. Determines which B1WebAPI method to call. (eg: GetPendingOrders).

 

 

The Message message source type pulls all of the integration messages of a specific kind from the given folder for processing by the actions and branches.

 

Example

 

Attributes

"Message" Type Attributes

 

Attribute	Definition
SourceFolder	(Required) Specifies which workflow folder to use as a filter for retrieving messages.
DefaultFailFolder	(optional) Defined in the Base MessageSource attributes, above.
SuccessFolder	(optional) Defined in the Base MessageSource attributes, above.
B1ObjectType	(optional) This parameter indicates to only retrieve specific B1 object types from the SourceFolder.

 

 

The http request type executes the specified URL and expects to receive an XML response representing an integration message(s). The results of this could then be processed by a standard action or in some cases a splitter action.

 

The http post type will “post” to a specific URL. The result of this can be processed by an action via the workflow engine.

 

FTP Message Sources

FTP message sources establish an FTP connection with the specified host, and download files in the configuration location and file formats.

• specifies that the files to be processed may be of any file format.
• specifies that the files to be processed are XML format.
• specifies that the files to be processed are CSV format.

 

Example

 

Attributes

FTP

 

Attribute	Definition
AnonymousAuthentication	(optional) [true|false] If enabled (true) then username and password are ignored. Defaults to false.
FTPServerURI	(Required) Specifies the FTP ServerURI. May be part of a config file.
InputFolder	(Optional) The source folder for xml input files.
OutputFolder	(Optional) The folder import files are copied to.
Password	Required for authenticated FTP access. Can be omitted for AnonymousAuthentication=true. May be part of a config file. Specifies the FTP Password.
Port	(optional) May be part of a config file. Port used to connect to the FTP Host.
UserName	Required for authenticated FTP access. Can be omitted for AnonymousAuthentication=true. May be part of a config file. Specifies the FTP Username.

 

SFTP Message Sources

SFTP message sources establish an SFTP connection with the specified host, and download files in the configuration location and file formats.

• specifies that the files to be processed are XML format.
• specifies that the files to be processed are CSV format.

 

Example

 

 

Attributes

SFTP

 

Attribute	Definition
AnonymousAuthentication	(optional) [true|false] If enabled (true) then username and password are ignored. Defaults to false.
Host	(Required) Specifies the FTP Host. May be part of a config file.
InputFolder	(Optional) The source folder for xml input files.
OutputFolder	(Optional) The folder import files are copied to.
Password	Required for authenticated FTP access. Can be omitted for AnonymousAuthentication=true. May be part of a config file. Specifies the FTP Password.
Port	(optional) May be part of a config file. Port used to connect to the FTP Host.
UserName	Required for authenticated FTP access. Can be omitted for AnonymousAuthentication=true. May be part of a config file. Specifies the FTP Username.

 

 

Custom Message Sources

The workflow framework supports the ability to write your own custom message source objects to implement logic that is specific to your solution. The Magento connector solution has implemented its own message source as shown in the example below.

 

Example

 

 

In this example, The class MagentoPendingOrders simply has to inherit from the MessageSource class in the Workflow framework and implement the following required methods:

• GetMessages - This is the main processing method that will be executed when the workflow runs. It will be passed a string parameter called workflow batchID that can be used to uniquely identify any transactions taking place as part of this workflow. The workflow engine expects your class to create a WorkFlowReponse object and fill the SourceMessages property with the WorkflowMessage objects that you want to be processed.
• ValidateMessageSource - This is a validation method that is called before any processing is completed. You can complete any required configuration checks in this section and stop the workflow from processing.
• DebugMessageSourceTrace - This method will be called when the workflow TRACE=ON is set. Normally you would enter any debug type messages or logging in this method that would be useful for troubleshooting errors in a production environment.
• ErrorMessageSourceTrace - This method will be called when an exception is encountered during the message source GetMessages execution. You should log the errors or handle the failures in this method.

 

In order to complete the configuration of your custom message source you will need to populate the CustomWorkFlowClass section of the workflow service B1WorkFlowService.config file. You will also have to make sure your custom dll is in the /bin/ directory of the service. This is an example of how that was done for Magento:

 

 

 

Sender Object

This object enables users to send messages to an external resource from the Workflow Processor. The result of a Sender object is always one or more messages that can be sent to any external resource as required. It will support most of the same types as the MessageSource object but it can be used during the workflow like an Action object (see [Actions] for more details).

 

For example:

 

Message Source Configuration

Most of the message source objects that will be used with the Workflow Engine for InterConnect will require some configuration information. This information is defined in an external XML file located in the Config folder of the Workflow Service. The file MessageSourceConfig is configured during implementation and loaded by the workflow engine.

Example configuration XML for a Magento Connector

 

RetrySettings Element

This element contains information about the retry capabilities of this workflow. Retries in this instance refer to the ability of the workflow to retry transactional-type actions such as B1Object etc.

 

Example

 

Attributes

• AllowRetry – [true|false] - This Boolean flag determines if the workflow will save messages for retry functionality. Defaults to true. If this is false it is assumed the retries will be handled via custom code.
• MaxRetries – Sets the maximum number of times a particular message will be retried before it is moved into the failed status, defaults to 3.
• RetryInterval – Sets the retry interval, in minutes, for any messages generated by the workflow. Defaults to 5.
• RetryFolder - Sets the folder where retry messages are stored while pending retry.

 

Schedule Element

This element contains information about how the workflow is executed.

 

Example

 

Attributes

• Type - [Polling|Daily]
  • Polling runs on regular intervals, as set by the WaitTimeInSeconds attribute.
  • Daily runs on a daily schedule.
• WaitTimeInSeconds - When type is set to Polling, this attribute sets the polling interval. Ignored otherwise. For production systems, a wait time of 300 seconds or more is recommended.

 

 

 

Previous

Next

---

  

Last modified: 11/13/2023/11:09 pm