OIEP - Configuration Section

The following sections are available when the STEP Exporter processor or the Business Rule Based Message processor is selected for an OIEP. For both processors, the Configuration section includes the same parameters for both Event-Based and Select Objects endpoints. Each parameter is described below.

Process Engine

STEP Exporter is the only processing engine option on a standard STEP system.

  • For the GDSN processor or the Business Rule Based Message Processor, different or additional sections are displayed.

  • The Datasheet PDF Creation process engine is only available for print customers. Refer to the OIEP - Configuration Section for Datasheet PDF Creation topic for more information.

  • If you need a customized processing engine, contact Stibo Systems.

The processing engine is originally selected in the wizard when configuring the endpoint. For more information, refer to OIEP - Event Based - Configure Endpoint or OIEP - Select Objects - Configure Endpoint.

Error Handling & Reporting

The 'Error Handling & Reporting' parameter is not included in the wizard, but it can be configured from the OIEP editor to send an error report to the specified email addresses if a background process fails or has error or warnings. The email alert contains information about the failed endpoint, including the server name, the background process, failed file, failing process step, and the cause of the error. A standard STEP system (without custom extension) includes only the 'Send Error Report' option.

For the Error reporter plugin to send email, the SMTP server must be configured on the application server. For information on configuring email from STEP, refer to the Email from STEP topic in the Resource Materials online help documentation.

Configure Error Handling and Reporting

  1. Open the relevant OIEP on the Configuration tab, open the Configuration section and click into the Error Handling & Reporting parameter to display the ellipsis button ().

  2. Click the ellipsis button () to display the Error Handling and Reporting dialog.

  3. For Connection Error Handling, the default is no connection error handling. The Retry Duration parameter is ignored when 'No' is set for the Retry Connection parameter. Enabling Connection Error Handling allows automated reconnection attempts when the external system is unavailable. When connection retries begin, a warning is logged to the Execution Report; if a connection cannot be established after the Retry Duration expires, an error message is logged to the Execution Report.

    • On the Retry Connection parameter, set 'Yes' to automate reconnection attempts for HTTP-based delivery methods including Amazon SQS, Cloud Blob Storage, Git, Kafka, REST, REST Direct, and SFTP. A 'No' setting requires manually restarting the OIEP if the connection fails.

      Note: Authentication-related connection errors are not retried and the OIEP fails immediately.

    • On the Retry Duration parameter, when blank, the default or 30 days is applied. Valid settings are an integer plus one of the following time indicators: s (seconds), m (minutes), h (hours), and d (days). For example, 45m indicates that connection retries will continue for 45 minutes, during which time, the OIEP shows a 'Failed (retrying)' state. Multiple integers with time units in order of size may also be used. For example, 1h45m30s indicates that connection retries will continue for 1 hour, 45 minutes and 30 seconds. After the 'Retry Duration' expires, if the connection cannot be re-established with the last retry, the OIEP fails, and email alerts are distributed based on the 'Select Error Reporter' settings. For more information, refer to the Running an Outbound Integration Endpoint topic.

  4. For Select Error Reporter, select an option:

    • Send Error Report: Use the following parameters to add a relevant email address (or use a semi-colon to add more than one email address) or group email that can be used to receive error and warning reports. When emailing multiple accounts, consider creating a group email and use that email address in the parameters instead of adding multiple email addresses for individuals. With this configuration, a single email group can be updated as the group members change while the 'Select Error Reporter' parameter remains unchanged.

      Note: To send email, the SMTP server must be configured on the application server. For information on configuring email from STEP, refer to the Email from STEP topic in the Resource Materials online help documentation.

      The email alert contains information about the failed endpoint, including the server’s name, the background process, failed file, failing process step, cause of the error, and a copy of the file that triggered the error.

      If no email address is entered, the alert(s) are sent to the email address of the user who created the integration endpoint. If no email is defined for this user, or if no mail server is defined in the configuration, the error report will be written to the failed Background Process Execution Log.

      • Email Address(es) for Process Failure Notifications: Sends an alert email to the listed address(es) when a fatal processing error occurs that puts the IIEP in a 'Failed' state.

      • Email Address(es) for Error Notifications: Sends an alert email to the listed address(es) when data warnings and/or errors occur that do not cause the process to stop.

      • Include Warnings in Error Notifications: A 'Yes' setting means alert emails include information on both warnings and errors. A 'No' setting means only error information is addressed in Error Notification emails. To receive an email when the IIEP enters the 'Failed (retrying)' state, set this option to ‘Yes.’

    • No Error Report disables the error reporter and no notifications by email are sent.

      Note: If the error report is larger than the default maximum, 10 MB, the report will not be attached to the auto-generated email sent to the configured email address(es). If the default maximum is not suitable, an admin can set the following case-sensitive property in the sharedconfig.properties file on the application server to adjust the maximum file size:

      Integration.Endpoint.ErrorFileSizeLimit={MB size}

      Replace the '{MB size}' element with the maximum MB file size allowed for error report attachments. Error reports larger than this configured maximum are not attached to the email.

Schedule

The schedule parameter is not included in the wizard, but it can be configured to repeatedly run the OIEP. For Select Objects OIEPs, the background processes runs as scheduled, regardless of changes to the data. For Event-Based OIEPs, the background process runs as scheduled but only when events are available for processing.

Important: Consider the time zone of the application server compared to that of the workbench (the client) where the schedule is created or viewed. When scheduling a job, the local time zone is displayed in the workbench, but the time zone of the server is used to run the background process. Although displayed, the time zone of the client is not included in the instruction to the server to run the job. This can cause confusion about when the job will run since the scheduled time is not automatically converted to accommodate potential differences in time zones.

  1. On the relevant OIEP, click the Configuration tab and open the Configuration section. Click into the Schedule parameter to display the ellipsis button ().

  2. Click the ellipsis button () and then select one of the following options:

    • Never - invoke the endpoint manually, no additional parameters are required, and no schedule is applied. This is the default setting and should be used while testing your endpoint.

    • Every - automatically run the endpoint repeatedly, every selected number of minutes. One (1) minute is the shortest interval allowed and is closest to real time. Enter the number of minutes in the text box. The selection is summarized at the bottom of the dialog.

    • Weekly - automatically run the endpoint repeatedly, based on the selected time, start and end dates, and days of the week. Use this option if a daily schedule is needed. The 'Start at' parameter determines the time of day that the endpoint will run. The 'Start on' parameter determines the date the endpoint will first run, while the 'End on' parameter determines the date of the endpoint's final run. The 'Every' checkboxes determine the days of the week when the endpoint will run. The selections are summarized at the bottom of the dialog.

    • Monthly - automatically run the endpoint repeatedly, once a month, based on the selected time, start and end dates, week of the month, and day of the week. The 'Start at' parameter determines the time of day that the endpoint will run. The 'Start on' parameter determines the date the endpoint will first run, while the 'End on' parameter determines the date of the endpoint's final run. The 'Every' dropdown parameter selections for the week of the month and the day of the week determine when the endpoint will run. The selections are summarized at the bottom of the dialog.

    • Later - automatically run the endpoint only once, at the time and date specified. The selections are summarized at the bottom of the dialog.

  3. Select Refresh collections before each run if the outbound integration endpoint contains collections that should be automatically refreshed before each run.

    Important: Only one collection per OIEP should be used at a time. If the collection includes unapproved objects, they might be lost upon refresh if the OIEP is configured with an Approved workspace setting.

Priority

When the recommended 'One Queue' priority-based BGP execution mechanism is configured, waiting BGPs are prioritized for execution based on the priority of the BGP and the created time. The legacy 'Queue for Endpoint' and legacy 'Queue for Endpoint Processes' parameters are not available. Refer to the BGP One Queue topic in the System Setup documentation.

Legacy Queue for Endpoint

This legacy option is not available when the recommended One Queue, priority-based background process (BGP) execution mechanism is configured. (Refer to the BGP One Queue topic in the System Setup documentation.)

In a legacy implementation (BGP Legacy Multiple Queues), 'Queue for endpoint' is the name for the queue that is used by the OIEP Background Process to poll the endpoint. The background process handles the actual export. The first time you activate the endpoint, a queue with the specified name is created if it does not already exist. Typically, high-priority integrations and integrations with long-running processes should have their own queue for endpoint processes.

If in doubt about how to populate this parameter, create a new queue for the OIEP, for example, including the OIEP ID in the name.

Legacy Queue for Endpoint Processes

This legacy option is not available when the recommended One Queue, priority-based background process (BGP) execution mechanism is configured. (Refer to the BGP One Queue topic in the System Setup documentation.)

When the legacy multiple queues execution mechanism is implemented (BGP Legacy Multiple Queues) STEP allows you to define separate queues. 'Queue for endpoint processes' is the name for the queue that is used by the background processes started by the endpoint to handle the actual export. The queue is automatically created on the system if it does not already exist. High priority integrations or integrations with long-running processes should typically have their own queue, for example, including the ID in the queue name.

Transactional Settings

'Transactional Settings' can be used for 'Select Objects' OIEPs, but the 'Strict' mode is required for 'Event-Based' OIEPs. For details, refer to the Integration Endpoint Transactional Settings topic.

Maximum Number of Threads

Although 'Maximum Number of Threads' is available on the Configuration tab for both static and event-based OIEPs, the setting only affects event-based processes. The default thread setting is one (1) which causes the endpoint to produce a single message at a time, with all events in the batch processed serially. Increasing the thread number results in each batch size being divided by the thread number so that the contents of a batch can be processed in parallel. For more information, refer to Event-Based OIEP Multithreading Support topic.

Maximum Number of Waiting Processes

'Maximum Number of Waiting Processes' specifies the maximum number background processes an endpoint can start to handle messages.

By default, the maximum number of waiting processes is set to 1000 for 'Transactional Settings' of Chain or None. When the 'Transactional Settings' parameter is Strict, this value must be 1. Changing an endpoint to have a 'Transactional Settings' of Strict updates this parameter to 1.

Maximum Number of Old Processes

'Maximum Number of Old Processes' specifies the maximum number of ended processes the system retains. This auto-cleanup option deletes succeeded and ended processes started by the OIEP when the limitation is exceeded. The oldest processes are deleted first.

By default, the maximum number of old processes is set to 1000.

Maximum Age of Old Processes

'Maximum Age of Old Processes' specifies the maximum age of succeeded and ended processes. Use the following case-sensitive notation: y = years, M = months, w = weeks, d = days, h=hours, m = minutes, and s = seconds.

By default, the maximum age of old processes is set to one (1) year.

Context Mode and Contexts

When exporting data in the STEPXML format or when using a custom cross-context enabled format, one file can contain data from multiple contexts. For other formats, the standard context splitter post-processor should be used. Using this option, separate files are generated for the selected contexts. For more information, refer to the OIEP - Post-processor - Context Splitter topic.

By default, the context is set to the one which is currently being used while creating the OIEP.

Changing Selected Contexts

The following image shows the Standard Format where a single context can be selected.

This image shows the Cross Context Format where a multiple contexts can be selected.

An explicit choice on whether the STEP Exporter should run in 'Standard Format' or 'Cross Context Format' mode is made when setting up the OIEP. It is possible to use cross context mode for endpoints with only a single context selected. This means that it will not be necessary to change downstream systems should more contexts be added later. For endpoints in 'Standard Format' mode (with just one context configured), it will not be possible to add more contexts without explicitly changing the export mode first.

  1. Click the Contexts field to display an ellipsis button ().

  2. Click the ellipsis button () to display the ‘Select Contexts’ dialog.

  3. Choose the desired contexts and click the Select button to save.

The configuration variants are shown in the examples below.

Single context, 'Standard Format'

Single context, 'Cross Context Format'

Multiple contexts, 'Cross Context Format'

When more than one context is selected, Context Mode becomes read-only and set to Cross Context Format (as shown above). The only way to revert to Standard Format is to deselect contexts until only one remains.

Workspace

Workspace defines which data is used for the export. Common setup is to use the Approved workspace, except when you need to generate events for objects before they are approved, for example, during import or from a workflow.

By default, the Approved workspace is selected.