5 Creating Orchestrations with Orchestrator Studio 9.2.4

This chapter contains the following topics:

5.1 Creating Orchestrations

This section contains the following topics:

5.1.1 Understanding Orchestrations

Creating an orchestration in the Orchestrator Studio involves:

  • Naming the orchestration and specifying the input format for the orchestration.

  • Adding inputs to the orchestration.

    The inputs define the data that is passed to the orchestration from a device, third-party application, custom program, or Cloud service. For example, an orchestration that is designed to receive input from a sensor, will receive an input that may include an ID that identifies the sensor, and data such as temperature, date, or any other data you want to capture from the sensor.

  • Adding steps to the orchestration.

    Each step is a component of the orchestration. A step can be a service request, rule, cross reference, or white list. At a minimum, an orchestration requires a service request step, which provides the actions or the instructions to perform a particular task in EnterpriseOne.

  • Configuring transformations.

    You use transformations to map orchestration inputs to inputs that are defined in each orchestration step, such as inputs in a rule, cross reference, white list, or service request component.

Important:

Remember that when you are ready to "request to publish" an orchestration, you need to make sure that you also request to publish all the components that are associated with the orchestration. The request to publish the components ensures that an administrator saves all the required components to the proper directory on the AIS Server for processing by the Orchestrator. If a component is missing, the orchestration process will end in an error.

5.1.2 Creating an Orchestration

To create an orchestration:

  1. On the Orchestrator Studio Home page, click the Orchestrations icon.

  2. On the Orchestrations side panel, click the New button.

  3. On the Orchestrations design page, enter a unique name for the orchestration in the Name field. Do not include special characters in the name.

    All orchestrations that are created in Orchestrator Studio 9.2.4 or later are saved as version 3 orchestrations. You cannot change this value. If you want to update a version 3 orchestration that was created in a previous version of the Orchestrator Studio, see Updating to Version 3 Orchestrations.

    Note:

    When you save an orchestration, the orchestration name is used to define an endpoint on the AIS Server. The endpoint URL is:

    http://<server>:<port>/jderest/orchestrator/<orchestrationname>

    To invoke this orchestration, third-party applications or devices use a post operation to this url, where <orchestrationname> is the name of the orchestration.

  4. Click the Product Code drop-down list to select a product code to associate with the orchestration.

    This enables an administrator to manage UDO security for orchestration components by product code.

  5. In the Description field, enter a short description with a maximum of 200 characters. This description appears along with the orchestration name in the component list.

  6. Click the Long Description button to provide more detail about the component.

    Use this field to describe the purpose of the orchestration and any details that differentiate the orchestration from other orchestrations that you create.

    At this point, the design mode is enabled for the orchestration and the canvas displays the Start and End nodes of the orchestration as shown in the following figure:

    This image is described in surrounding text.
  7. Click Save before defining inputs or adding steps for the orchestration.

    The Orchestrator Studio saves the orchestration as a "Personal" UDO. Next, add inputs to the orchestration as described in Adding Inputs to an Orchestration.

    You can also use the Save As button and rename an existing orchestration to create a new one.

Caution:

If you use Save As to create a copy of an orchestration, only the orchestration is copied. The Orchestrator Studio does not create a copy of the components that are associated with the steps of the orchestration. That is, both the original orchestration and the new orchestration use the same components that are included in the orchestration. Therefore, in the new orchestration, do not modify the components in any way that would break other orchestrations that use the same components.

5.1.3 Adding Steps to an Orchestration

Each component (data request, form request, rule, cross reference, white list, and so on) that you add to an orchestration is an orchestration step.

5.1.3.1 Adding the Initial Step to an Orchestration

  1. In an Orchestration, click the Design Mode button at the bottom-left corner of the canvas area.

    A plus sign (+) appears in the orchestration path between the Start and End nodes.

  2. Click the Add Step button (+).

    Alternatively, double-click the path in between the Start and End nodes in the orchestration.

  3. In the New Step Type drop-down list, select one of the component types to add to the orchestration.

    The following figure shows the New Step Type drop-down list.

    This image is described in surrounding text.
  4. The Orchestrator Studio displays a list of objects for the corresponding component type.

  5. Define the component for the step:

    1. To use an existing component for the new step, search and select a component from component list.

    2. To create a new component for the step, click the New button to access the design page for creating the new component.

      After creating the component, when you return to the orchestration, the component is added a new step to the orchestration.

    The Orchestrator Studio adds the component as a step to the orchestration as shown in the following figure:

    This image is described in surrounding text.

5.1.3.2 Adding Additional Steps to an Orchestration

  1. In the Design Mode of the orchestration, select the location in the orchestration path where you want to add step.

  2. Click the Add Step button.

    Alternatively, double-click the path at the location where you want to insert a step in the orchestration and select the component type from the New Step Type drop-down list. For example, you can add a white list to an existing orchestration, as a step before the other steps or in any other location in the orchestration.

  3. In the New Step Type drop-down list, select the component type that you want to add.

  4. In the component list that is displayed, search and select the component that you want to add.

The Orchestrator Studio adds the new component as an additional step to an orchestration.

The following figure shows an orchestration that contains a rule and form service requests steps:

This image is described in surrounding text.

Each box in the orchestration canvas represents a step in the orchestration. For information about the other features of the canvas, see Working with the Graphical Representation of an Orchestration.

  • Name. Displays the name of the component.

  • Type. Each component type is displayed in a unique icon: Rule, Form Request, Cross Reference, White List, and so on.

  • Action (True or False). Define which subsequent component is invoked based on the criteria in the preceding rule. See Defining the Actions Between a Rule and Dependent Components for details.

As the next task, add and map the orchestration inputs to inputs in the orchestration steps. See, Adding Inputs to an Orchestration and Mapping Orchestration Inputs.

5.1.3.3 Removing a Step from an Orchestration

Caution:

Before you delete a step, make sure the step is not used by any other component in the orchestration.
  1. In the Design Mode of the orchestration, select the component box that you want to remove.

    The action control icons are displayed for the component.

  2. Click the Remove Step icon to remove the component from the orchestration.

If you make a mistake when updating an orchestration, select the Restore option from the Manage drop-down menu to restore the orchestration to its last saved version. This action erases any changes made since the last save.

5.1.3.4 Moving a Component in the Orchestration

You can use the Cut Element and Paste Element options to move a component within an orchestration. You can move a component within an orchestration, but not across different orchestrations.

To move component in an orchestration:

  1. Open an orchestration in the design mode.

  2. Select the component in the orchestration that you want to move.

    The action control icons for the component are displayed.

  3. To move or cut a component, click the Cut Element icon.

    When you use the Cut Element option, the selected component is copied to the clipboard. At this point, the Paste Element icons appear in the orchestration path.

  4. Click the Paste Element icon at the location in the orchestration where you want to place the component.

  5. Save the orchestration.

5.1.3.5 Defining the Actions Between a Rule and Dependent Components

TThe Orchestration design page enables you to define the actions between a rule component and other components in an orchestration. After you create a rule with conditions and add the rule as a step to an orchestration, you need to define the action the orchestration takes if the condition in the rule is met. For example, if the orchestration needs to invoke a service request when the condition of a rule is met, then in the path for True, you have to add the service request.

You can also define a False action to invoke a different orchestration component when a condition in a rule is not met. A False action can invoke a different service request or another rule that contains additional conditions for which the incoming data is evaluated. Thus, you can design an orchestration with as many rules and service requests as your business requirements necessitate.

The following figure shows an example of an orchestration with two rules and two service requests, with the following defined actions:

  • When the condition in the first rule step is met (True), the action is set to instruct the orchestration to invoke a form request step.

  • When the condition in the first rule step is NOT met (False), the action is set to instruct the orchestration to invoke a second rule.

  • When the condition in the second rule is met (True), the action is set to instruct the orchestration to invoke a second form request.

Figure 5-1 Defining the Rule Actions

Description of Figure 5-1 follows
Description of ''Figure 5-1 Defining the Rule Actions''

To set the steps for True or False conditions of a Rule:

  1. In the Orchestration design mode, add a Rule component to an orchestration.

  2. In the orchestration path for True, click the Add Step button (+) to add a step for the true condition.

  3. Similarly, in the orchestration path for False, click the Add Step button (+) to add a step for the false condition according to your requirement.

  4. Click the Save button.

After completing the orchestration, you can use the Run Orchestrations page to test the orchestration in a test environment. You can access the Run Orchestrations page from the Tools drop-down menu in the upper-right corner of the Orchestrator Studio. See Chapter "Testing Orchestrations" for more information.

5.1.3.6 Defining Error Handling for Orchestration Steps

You can set up error handling for individual orchestration steps. In an orchestration step, you can determine how the Orchestrator handles an error. You can determine whether the Orchestrator:

  • Continues processing the orchestration after the error occurs, effectively ignoring the error.

  • Cancels the orchestration.

  • Cancels the orchestration and invokes an alternate orchestration or notification. For example, the orchestration might call a notification to alert subscribers if an orchestration is canceled. Or run an orchestration to clean up work already performed by the orchestration before it was canceled.

You have the option to either include additional text in the error, or to include a variable to pass a value into the error text.

Regardless of the option you choose, the system still generates an exception when it encounters an error with an orchestration step. For more information on how to monitor exceptions, see Orchestrator Health and Exception Monitoring.

To define error handling for an orchestration step:

  1. In the orchestration design page, click the component step.

    The action control icons are displayed for the component.

    Surrounding text describes error_handling.png.
  2. Click the Error Handling icon.

    The Error Handling dialog box displays the type and name of the step, as shown in the following figure:

  3. In the User Defined Error Text field, you can enter additional details about the error to display in the exception details. You can insert variables in the error text using the ${} notation, where you enter the variable name between the braces.

    If you configure the step to continue on error, this error text will appear in the response in a new array: "Continued on Error." If you configure the step to abort on error, this text will appear in the returned exception: userDefinedErrorText. The error text is also added to the AIS Server log.

  4. For On Error, select one of the following options:

    • Abort

    • Continue

  5. (Optional) If you choose to Abort on error, you can configure the orchestration step to invoke another orchestration or notification:

    1. Click the Assign Orchestration/Notification button and select an orchestration or notification to invoke after an error.

    2. Map the inputs as appropriate.

5.1.4 Adding Inputs to an Orchestration

Orchestration inputs identify the data an orchestration consumes from a calling custom program, a third-party application, a mobile application, an equipment meter, an IoT device, or a Cloud service. For example, you could have an orchestration that consumes data from an equipment manufacturer, with an "EquipmentID" input to pass the meter reading of the equipment to the orchestration.

For each input, you specify an input type, which can be a string, a numeric value, or various date formats. You can add four types of inputs to an orchestration:

  • Orchestration Inputs.

    You can manually enter orchestration inputs, including arrays and objects, to identify the data an orchestration consumes from third-party applications or devices.

    After adding a component as a step in the orchestration, you can use the Add Inputs to Orchestration button in the Transformation dialog box to automatically add inputs that are defined in a component as inputs to the orchestration. You can remove any of the inputs as needed, and then map the orchestration inputs to the appropriate inputs in the orchestration steps.

  • Variables.

    You can enter variables that are available as inputs to other steps or that can be used to return data. To change the variable value in a step, you must define the variable value in the output of the step. When the step runs, the variable will change and will be available in future steps. This gives you the ability to declare variables at the beginning of an orchestration without having to specify them as orchestration inputs. As the orchestration progresses through its steps, it can use and redefine the values of these variables, and these values are available to the subsequent steps in the orchestration.

  • System Values.

    New orchestrations include the following default inputs: User Address Book Number, User Name, System Date, and Orchestration Input. These inputs represent the originator of the orchestration when executed at runtime. This gives you the option to map these inputs to an orchestration step.

  • Value from Steps.

    When you add a form request, data request, or cross reference that is configured to return values from EnterpriseOne, the variables that are defined to represent the return values appear as additional orchestration inputs. Therefore you can map the data returned from one component to a subsequent component in an orchestration.

    Also, if you add a service request step that generates output, the Orchestrator Studio automatically adds a <servicerequestname>.output as an orchestration input. This input includes a variable that represents the JSON output of the service request, and gives you the option to map the JSON to a subsequent orchestration step.

Each component that you add to an orchestration-a service request, rule, white list, or cross reference-also includes one or more inputs which evaluate data from orchestration inputs. For example, inputs in a rule evaluate data received from orchestration inputs to determine the next step in an orchestration. When you assemble an orchestration, you map the orchestration inputs to the inputs defined in the components. See Mapping Orchestration Inputs.

To manually add orchestration inputs in the Orchestration Inputs grid:

  1. On the Orchestrations design page, click the Start node.

    The action control icons are displayed above the Start node.

  2. Click the Inputs and Values icon.

  3. In the Inputs and Values dialog-box, click the Input Format drop-down menu and select the appropriate format:

    • JDE Standard

    • Generic

    See Supported Input Message Formats for more information about which input format to use.

  4. In the Orchestration Inputs tab of the Inputs and Values dialog box, enter the name of the input in the Input column.

  5. In the Value Type column, select the input value type. Valid values are:

    • Array

      Note:

      Array is not a valid value type if you are adding a variable input.

      If you add an array for an input, the grid expands so you can define the inputs in the array.As shown in the following example, a user added an array named GridData. And then entered the inputs "Update Row" and "Quantity" for the array in the subsequent rows.

      Surrounding text describes array.png.
    • String

    • Numeric

    • Boolean

    • Object

      This input type allows you to pass a JSON object into an orchestration. You can use this input type to pass nested arrays of data by defining arrays of objects.

    If the input is a date, you can use any of the following date formats:

    • dd/MM/yyyy

    • dd/MM/yy

    • yyyy/MM/dd

    • MM/dd/yyyy

    • MM/dd/yy

    • yy/MM/dd

    You can also use the following date formats that create additional inputs derived from the passed value:

    • Milliseconds

    • yyyy-MM-dd'T'HH:mm:ss.SSSZ

  6. Optionally, use the Default Value column to enter a default value that you want to pass through the orchestration input.

  7. Click Save to save your changes.

To generate orchestration inputs from an orchestration component:

  1. In the orchestration design page, click the component from which you want to generate the inputs.

    The action control icons are displayed for the component.

  2. Click the Transformations icon.

  3. In the Transformations dialog box, click the Add Inputs to Orchestration button.

  4. Click the Start node and then select Inputs and Values icon from the action control icons.

    In the Inputs and Values dialog box, the inputs that are defined in the component appear as inputs to the orchestration.

  5. Use the X button at the end of each row to remove any unnecessary inputs.

  6. Modify the Value Type and Default Value columns as needed.

  7. Click on the canvas to close the Inputs and Values dialog box and then click Save.

See Mapping Orchestration Inputs to map these inputs to the appropriate component inputs.

5.1.5 Mapping Orchestration Inputs

On the Orchestration design page, access the Transformations dialog box to map orchestration inputs to the inputs that are defined in an orchestration step, such as inputs in a rule, cross reference, white list, or any other component. The Transformations dialog box includes an Auto Map button for automatically mapping any matching inputs in the orchestration and the orchestration step.

If an orchestration and an orchestration component use different input names to identify the same data, you can use the grid in the Transformations dialog box to map the inputs. This facilitates the reuse of components, and eliminates the need to create a new component to match the input names (from a third-party application or device) in a new orchestration.

To better understand how to map inputs, see the example depicted in Figure. In this example, the orchestration inputs have the same name as the inputs in the service request. These inputs were automatically mapped using the Auto Map button.

Figure 5-2 Transformations Example

Description of Figure 5-2 follows
Description of ''Figure 5-2 Transformations Example''

Initially, when you have a small number of orchestrations in your system, it is recommended to keep all the input names consistent among the orchestration and all the components (orchestration steps) used by the orchestration. But as your library of orchestrations and orchestration components increases, instead of creating new components with input names that match the names of the orchestration inputs, you can use transformations to map the orchestration inputs to an existing component.

To map inputs:

  1. In the orchestration design page, click the component to which you want to map orchestration inputs.

    The action control icons are displayed for the component.

  2. Click the Transformations icon.

  3. In the Transformations dialog box, click the Auto Map button to map matching inputs. The Studio automatically maps inputs with the same name, and the matching orchestration inputs appear in the Available Values column next to the matching input in the Input column.

  4. To map an orchestration input to an orchestration step input that does not have the same name:

    1. In the grid, click the drop-down menu in the Available Values column.

    2. Select the orchestration input to map to the orchestration step input.

  5. You can map a literal value to the orchestration step input by entering a value in the Default Value column.

  6. If you are mapping values from an array, you can configure the orchestration to iterate over the orchestration step so that the step is called once for each row in the array:

    1. After defining the array in the Inputs and Values dialog box, click the Iterate Over drop-down list in the Transformations dialog box and select the name of the array input.

    2. Map the orchestration inputs for the array to the inputs that are defined in the orchestration step.

5.1.6 Retrieving and Passing Data Sets in an Orchestration

You can configure a form request or a data request to return a data set. You can also configure an orchestration to pass a data set that is returned from a form request or a data request to another step in the orchestration. At runtime, the orchestration executes the form request or data request once per row in the data set.

The following figure shows an example of a data request that is configured with a data set named "Employees" and will retrieve the address book number and tax ID of all employee records in EnterpriseOne.

Figure 5-3 Data Request Configured to Retrieve a Data Set

Description of Figure 5-3 follows
Description of ''Figure 5-3 Data Request Configured to Retrieve a Data Set''

5.1.6.1 Configuring a Data Request to Retrieve a Data Set

  1. On the Data Requests design page, enter a name for the data set in the Data Set Variable Name field.

  2. Define the filtering criteria for the data set.

  3. In the grid, click the Return icon ( Return Icon) next to the fields that you want the data request to return in a data set.

  4. In the Return Fields and Variable Names section, enter a variable name for each return field.

    When you add this data request to an orchestration, you can use these variables to map the data in the data set to a subsequent orchestration step.

For more information about configuring a data request, see Configuring a Data Request.

5.1.6.2 Configuring a Form Request to Retrieve a Data Set

Note:

Data sets from grids on a power form are not supported.
  1. In the Form Requests design page, locate the row <Form Name> - Grid node in the Available Actions grid.

  2. In the <Form Name> - Grid row, enter a name for the data set in the Variable column.

    If you configure the orchestration to pass the data in the data set to a subsequent orchestration step, you enter this variable name in the Iterate Over column of the orchestration step to which you want to pass the data.

  3. For each row that you want to include in the data set, slide the toggle in the Return column.

  4. For each row that you want to include in the data set, enter a variable name so that the returned column can be mapped to a subsequent orchestration step.

For more information about configuring a form request, see Configuring a Form Request in the Orchestrator Studio.

5.1.6.3 Passing a Data Set to a Subsequent Orchestration Step

You can configure an orchestration to pass each row of a data set to an orchestration step.

  1. Add the form request or data request defined with a data set to the orchestration.

  2. In the Transformations dialog box of the orchestration step, in the Iterate Over drop-down list, select the data set name that is defined in the form request or data request.

  3. Map the data set fields to the inputs in the orchestration step. See Mapping Orchestration Inputs.

  4. Click Save.

5.1.7 Working with Orchestration Output

Orchestration output can include values from fields and grid columns that you specify as returns when setting up a form request, data request, or cross reference in an orchestration. Orchestration output can also include the response from a connector, custom service request, or the result of a rule (true or false).

On the Orchestration Output dialog box, you can use Groovy scripting to manipulate the contents of the response to refine the orchestration output as required by the parameters in the consuming device or program.

To work with orchestration output:

  1. In the orchestration design page, click the End node.

    The action control icon is displayed for the End node.

  2. Click the Orchestration Outputs icon.

    The grid displays all the components or steps in the orchestration that contain return fields, as shown in the following example:

    Description of orch_output.png follows
    Description of the illustration ''orch_output.png''

  3. If you want to view the JSON code of all the return fields in an orchestration, slide the Select All toggle to the right.

    You can individually select the return fields for which you want to preview the JSON code. You can expand each step to see the return fields. The Output column displays the name that is defined for a return field.

    1. In the Select column, slide the toggle of the any return fields that you want to add to your orchestration output and then exit the Orchestration Outputs page.

      The fields will be returned in JSON format, which you can test on the Run Orchestrations page.

    2. You can change the name for the return fields in the Output column.

  4. You can edit the provided Groovy script template in the Manipulate tab to manipulate the contents of the response to refine the orchestration output.

    See Groovy Template for Manipulating Output from an Orchestration Response for more information.

  5. To save the orchestration outputs, return to the Orchestrations design page and click Save.

5.2 Creating Schedules for Orchestrations

This section contains the following topics:

5.2.1 Understanding Schedules

The Orchestrator Studio enables you to create and assign a schedule to an orchestration. A schedule determines how often the Orchestrator executes an orchestration. For example, with a schedule, you can create an orchestration that regularly checks for a Watchlist threshold, and sends a notification to the appropriate users when the threshold is exceeded.

You define a schedule using minutes, hours, days, or a Cron string. Cron is a scheduling utility in which cryptic strings are used to define an interval. Then you associate a schedule to an orchestration to determine how often the orchestration runs. You can attach the same schedule to multiple orchestrations.

You must have been granted required UDO security to create schedules. Schedules are managed as UDOs. As a result you need the proper UDO security to publish and share your schedules for others to use, or use schedules that others have published.

The scheduler is a process on the Application Interface Services (AIS) server that starts, stops, and manages schedules. An administrator uses the Scheduler page to start and stop schedules.

5.2.2 Creating a Schedule

Create a schedule to define how often the Orchestrator should execute an orchestration. You can define a schedule using minutes, hours, days, or a Cron string. Cron is a time-based job scheduler that can be used to schedule jobs to run periodically at fixed times, dates, or intervals (for example, every Tuesday and Friday at 9:00 a.m.).

To create a schedule:

  1. Create a schedule as described in Creating a Component

  2. In the Schedules design page, enter a short description with a maximum of 200 characters. This description should clearly describe the frequency of the schedule so that the schedule can be attached to notification as needed.

  3. Perform one of the following steps:

    • In the Scheduled to run every section, select a number of minutes, hours, or days to define how often you want the schedule to run.

      If you select minutes, you cannot run more often than every five minutes.

    • In the Or Enter a Cron String section, enter a Cron string to define the schedule.

      Cron is a time-based job scheduler that can be used to schedule jobs to run periodically at fixed times and intervals, and on fixed dates. Many third-party Cron expression generators are available that can help you create a Cron string.

  4. Click the Save or Save As.

A new schedule is saved for the first time as a "Personal" UDO. Thereafter, you can use the UDO buttons described in the User Defined Object (UDO) Features section to move the schedule to the appropriate status.

5.2.3 Adding a Schedule to an Orchestration

Adding a schedule to an orchestration does not invoke the orchestration as scheduled. Starting the scheduler is a separate step. After you add a schedule, ask an administrator to start and administer the schedule using the Scheduler page. See, Working with Scheduler for more information.

Alternatively, you can use the REST API services to manage the schedules. For more information about REST API services for starting, stopping, and managing the Scheduler, see JD Edwards EnterpriseOne Tools REST API for the Application Interface Services Server.

Note:

In order to use the Scheduler with an orchestration, it must be a version 2 or version 3 orchestration. You can use the Orchestrator Studio 9.2.4.0 to migrate the version 1 and version 2 orchestrations to version 3 orchestration.

To add a schedule to an orchestration:

  1. Access the orchestration to which you want to add a schedule.

  2. In the canvas of the orchestration, click the Start node.

    The Orchestrator Studio displays the action control icons.

  3. Click the Schedule icon.

  4. On the Schedules dialog box, click the Select Schedules button.

  5. Select a schedule from the components list.

    The selected schedule is added to the Schedules dialog box. You can edit or remove the schedule and then close the Schedules dialog box.

  6. Click Save to save your changes.

Note:

If the message "You don't have authority." is displayed while adding a schedule to an orchestration, check if your token has expired.

5.3 Working with Scheduler

This chapter contains the following topics:

5.3.1 Understanding Scheduler

The Orchestrator Studio provides a user interface, which is called the Scheduler user interface, where you can view the notification and orchestration jobs along with the attached schedules. Using the Scheduler user interface, you can view all the jobs and perform tasks, such as starting and stopping individual or multiple jobs. The Scheduler user interface eliminates the need to use third-party applications to start and stop jobs. The Scheduler user interface enables you to designate a job that should be automatically started whenever the AIS server is started. This enables the scheduled jobs to be automatically started when the AIS server is restarted.

You must have been granted proper UDO security to work with the notification and orchestration jobs on the Scheduler user interface.

The Scheduler user interface provides information about the orchestration jobs that are running and the ones that need to be started.

The scheduler runs as a process on the Application Interface Services (AIS) server. You can view only those schedules on the AIS server that you are currently logged-in to. For information on designating the AIS server as a scheduler, see "Configuring AIS Server Manager Settings" in the JD Edwards EnterpriseOne Application Interface Services Server Reference Guide.

Note:

When a Scheduler server points to a JAS server that supports an environment, which is also supported on another Scheduler server pointing to another JAS server, two instances of the same job could exist. This is because the job is running for a specific environment and that environment is supported in two different scheduler configurations. This is applicable when the scheduler is not resilient.

5.3.2 Prerequisites

Complete the following prerequisites:

For information on scheduler resilience through the use of a database with your scheduler, see Configuring AIS Server Manager Settings in the JD Edwards EnterpriseOne Application Interface Services Server Reference Guide.

5.3.3 Accessing the Scheduler

To access the Scheduler user interface:

  1. Log in to JD Edwards EnterpriseOne Orchestrator Studio.

  2. On the Orchestrator Studio Home page, click the Scheduler icon to access the Scheduler user interface.

Set Up User Access to the Scheduler Program

An administrator must use EnterpriseOne application security to enable user access to the Orchestrator Studio (P98I0000) and Scheduler (W98I0000B) programs. See "Managing Application Security" in the JD Edwards EnterpriseOne Tools Security Administration Guide and "Managing Orchestrator Studio Security".

Enable UDO View Security to Orchestrations, Notifications, and Schedules

Users must have UDO view security access to the orchestrations, notifications, and schedules that they want to work with using the Scheduler user interface. For more information about UDO view security, see "Managing UDO View Security" in the JD Edwards EnterpriseOne Tools Security Administration Guide.

5.3.4 Scheduler User Interface Features

Use the Scheduler user interface to view, start, and stop notification or orchestration jobs with their associated schedules. This user interface enables you to review the state of the jobs that are running.

  • Jobs list. The Scheduler user interface displays a list of existing notification or orchestration jobs. By default, the list is displayed in the ascending order of the notification and orchestration names.

  • Select or Select All check box. Click the check box in the individual row to select specific jobs, or click the Select All check box to select all the jobs. Note that you can select only those jobs that are created by the currently logged-in user and have a schedule attached.

  • Sort Order button. Enables you to sort the jobs in ascending or descending order. When you hover the mouse over the column header, the Sort Order button is displayed next to column name. By default, the jobs are sorted in the ascending order of Notification/Orchestration Name.

  • Filter field. Search for specific notification or orchestration jobs in the list. The search runs over values in the Notification/Orchestration Name, Schedule Name, User, Environment, and Role fields. You can also filter the jobs based on the Notification ID and the Orchestration ID.

  • Scheduler uptime (d:h:m). Displayed when the scheduler server is running. Displays the duration for which the scheduler has been running in days, hours, and minutes.

    When the scheduler server is not running, the message "Scheduler not started" is displayed. For information on designating the current AIS server as the Scheduler server, see Configuring AIS Server Manager Settings.

    Note:

    If the current AIS server is not designated as a scheduler server, a message "AIS Server not designated as Scheduler" is displayed.
  • Restore button. Updates the notification and orchestration jobs displayed in the table so that the changes to the job information are reflected. For example:

    Jobs could have been started or stopped by another user by using the Scheduler user interface.

    Changes could have been made to the jobs using REST services.

    Changes could have been made to the jobs using the Work With Categories (P980059) application and so on.

    When using the Restore button, the values in the Filter field and drop-down selections are preserved.

  • i (About). Displays a dialog box that provides two sets of information: Scheduler information and JAS server information.

  • Scheduler Server. Indicates whether the AIS server to which you are currently logged-in is designated as a scheduler in Server Manager.

    • Scheduler Information

    • Resilient. Displays whether the scheduler is resilient.

    • Started. Displays whether the scheduler is running.

    • Running Since. Displays the date on which the scheduler started running and the duration for which the scheduler has been running.

    • JAS Server Information

    • Host. Displays the host JAS server URL.

    • Environment. Displays the environment to which the user is currently signed in.

    • Role. Displays the role that the user has currently signed in as.

    Note:

    If the current AIS server is not designated as a Scheduler server and the Scheduler server has been started using REST API, the Scheduler Server, Started, and Running Since fields are displayed in red color indicating that there is a configuration error. Also, you will not be able to start or stop any of the orchestration and notification jobs.
  • Close. Exit the user interface.

5.3.5 Working with Scheduler

Using the Scheduler user interface you can perform the following:

  • Use the Start selected button to start an individual or multiple notification and orchestration jobs that you have selected. The Start selected button is enabled only when you select a job from the notification and orchestration jobs list.

    When you click the button, the selected jobs are started and the Scheduler user interface displays the following information in a dialog box:

    • Jobs Selected. Displays the number of jobs that are selected.

    • Jobs Started. Displays the number of jobs that have been started.

    • Jobs in Error. Displays the number of jobs that have errors or were not started.

    • Already Started. Displays the number of jobs that are already running among the selected jobs.

    Alternatively, you can start an individual job by enabling the Start/Stop toggle in the Started column located in each row.

  • Use the Stop selected button to stop an individual or multiple notification and orchestration jobs that you have selected. The Stop selected button is enabled only when you select a job from the notification and orchestration jobs list.

    When you click the button, the selected jobs are stopped and the Scheduler user interface displays the following information in a dialog box:

    • Jobs Selected. Displays the number of jobs that are selected.

    • Jobs Stopped. Displays the number of jobs that have been stopped.

    • Jobs in Error. Displays the number of jobs that have errors or were not stopped.

    • Already Stopped. Displays the number of jobs that are already stopped among the selected jobs.

    Figure 5-4 Jobs Stopped

    Surrounding text describes Figure 5-4 .

    Alternatively, you can stop an individual job by enabling the Start/Stop toggle in the Started column located in each row.

    In the following example, the user is currently logged in as JDE, so the JDE user can access all the jobs that have JDE as the value in the User column. The JDE user can start the highlighted job by sliding the "Click to start job" toggle to the right. As the "Demo Get Item Availability" job also has JDE as the user, by sliding the toggle to left the user can stop the job.

    The rest of the jobs in this example are disabled because these jobs have LK as the value in the User column. The toggle in the Running column indicates that the job is already running.

    Figure 5-5 User, Role, and Environment

    Surrounding text describes Figure 5-5 .

    Note:

    You can start only those jobs that are created by the currently logged-in user using the current environment, and the current role that the user is logged-in as. You can stop all the jobs that are created by the currently logged-in user. For the rest of the jobs, the Start/Stop toggle is disabled.
  • Use the Started column to view the status of the notification and orchestration jobs for which you have access.

    Select one of the following values from the Started drop-down menu:

    • All. To view all the notification and orchestration jobs.

    • Started. To view only those notification and orchestration jobs that are currently being executed. This is the default option in the Started drop-down list.

    • Stopped. To view only those notification and orchestration jobs that are currently stopped.

  • Use the Type column to filter the notification and orchestration jobs. The icon in the column indicates if the job is an orchestration or a notification.

    You can click the notification or orchestration icon to open the corresponding notification or orchestration. To navigate back to the Scheduler user interface from the notification design page or orchestration, click the Scheduler link in the location link displayed at the top of page.

    Select one of the following values from the Type drop-down menu:

    • All. To view all the notifications and orchestrations.

    • Notifications. To view only the notification jobs.

    • Orchestrations. To view only the orchestration jobs.

  • Use the Product Code column to view the product code that was associated with the notification or orchestration when it was created. The Product Code drop-down menu displays all the product codes for the notifications and the orchestrations in the table.

    Selecting a product code from the drop-down menu displays only the associated notifications and orchestrations.

  • Use the Notification/Orchestration Name column to view the name of the notification and orchestration. When you click the notification or orchestration name, the corresponding description is displayed.

    Use the Filter field to look for specific notifications or orchestrations. Use the Notification/ Orchestration Name sort button to sort the jobs in ascending or descending order of the notifications and orchestrations names.

  • Enable the Auto Start toggle to designate a notification or an orchestration job to automatically start whenever the Scheduler server is started. For information on the autostart job records, see Scheduler Autostart Jobs Manager in the JD Edwards EnterpriseOne Tools Notifications Guide.

    Note:

    Enabling the Auto Start toggle does not start a job, but only designates the job to be started automatically whenever the Scheduler server is started. Use the Started toggle to start an individual job.
  • Use the Schedule Name column to view the name of the schedule when a notification or an orchestration has an attached schedule. When you click the schedule name, its corresponding description is displayed.

    Select one of the following values from the Schedule Name drop-down menu:

    • All. To view all the notification and orchestration jobs.

    • Schedule. To view only those notification and orchestration jobs that have a schedule attached. This is the default option in the Schedule Name drop-down list.

    • No schedule. To view only those notification and orchestration jobs that do not have any attached schedule.

    Note:

    When you select the No Schedule option for the Schedule Name column, you have to select the All option for the Started column to view the jobs in the list.
  • Click the Info icon to view the information about the job. When you click the Info icon, a dialog box appears displaying two sets of information: scheduled job information and health monitor.

    Scheduled Job Information:

    Displays the following data for the selected job that is associated with a specific user, environment, and role:

    • Notification or Orchestration Name

    • Notification or Orchestration ID

    • UDO Group

    • Last Run

    • Last Run Duration

    • Next Run

    • Total Runs

    • Schedule Name

    • Schedule ID

    • Interval

    • Consecutive Errors

    • % Errors

    • Total Errors

    For the jobs that are not executing currently, only the Notification or Orchestration Name and ID, Schedule ID, and Interval information are displayed.

    Health Monitor:

    Displays high-level information about the performance of the selected job. A bar-chart shows up to the last 10 instances that the job was executed, with each bar representing a single instance. The instances are listed earliest to latest, from left to right. A red bar indicates a failure. A green bar indicates a success. The height of each bar indicates the time taken to process the job. Move your cursor over each bar to see the date and time when the job was executed and the time in seconds taken to complete processing the job.

    Figure 5-6 Info

    Surrounding text describes Figure 5-6 .

    For more information, see Creating Orchestrations with Orchestrator Studio 9.2.4.

    The information that is displayed in the bar-chart for a job is based on the name of the notification or orchestration regardless of the user, environment, and role values.

    As shown in the following example, the Scheduled Job Information section displays the information only for the highlighted job with respect to the specific user, environment, and role. In the Health Monitor section, each bar in the chart could be for any of the instances of the job with the notification name "Demo_Sold to Capital System RAP with Overrides" regardless of the user, environment, or role values.

    The Info icon indicates an error when the icon is displayed in red.

  • Use the User, Environment, and Role columns to view the user, environment, and roles information for the jobs.

    • User

      The user who created the orchestration or notification. In the case of jobs that are currently executing, the User, Environment, and Role columns display the user who started the job.

    • Environment

      The environment that the user who created the orchestration or notification is signed in to. The environments listed in this column are the environments that are available on the JAS server that is connected to the current AIS server. Therefore, if you log in to a different AIS server, the environments are listed based on the environments that are supported on the JAS server for that AIS server.

    • Role

      The role of the user who created the orchestration or notification.

    Use the drop-down menus to filter the jobs based on user, environment, and role. The user who is currently logged in will not be able to select, start, or stop the jobs that have been created by another user.

    When you have jobs with the same notification or orchestration name running multiple times based on different user, environment, and role combinations, the Scheduler user interface lists the job that is associated with the currently logged-in user, the currently used environment, and current role of this user, as the primary record.

    Next, the jobs that are associated with the currently logged-in user but created in different environments and through other roles are displayed. Followed by the jobs with the same notification or orchestration name, but associated with different user, environment, and role values. These instances of the job with the same name are displayed in italics.

The Orchestrator Studio preserves the options that are selected for the drop-down menus in the Scheduler user interface. The next time you log in, the Scheduler user interface will display the jobs according to the selection made in the previous session.

Note:

For the User drop-down list, only the All Jobs and My Jobs options are preserved.

When you filter a job based on a Role or an Environment, the system preserves the filter values. However, if the next time you log in and no data exists for that selection (for example, you filtered based on a role that no longer has any jobs that are currently executing), the drop-down menu will display the value All.

5.3.6 Starting and Stopping Jobs using Scheduler

Using the Scheduler user interface, you can start and stop the orchestration jobs that have a schedule attached.

To start an individual orchestration job:

  1. Open the Scheduler user interface.

  2. Select the orchestration job you want to start.

    Note:

    You can only start the jobs that are associated with the currently logged-in user, the currently used environment, and the user's current role. The currently logged-in user cannot start the jobs that are created by another user.
  3. For the selected job, slide the toggle to the right in the Started column.

    Alternatively, you can click the Start selected button to start the selected orchestration job.

To start multiple orchestration jobs:

  1. Open the Scheduler user interface.

  2. Click the check box next to the Type column to select the orchestration jobs you want to start, or click the Select All check box to select all the jobs.

    Note:

    You can only start the jobs that are created by the currently logged-in user, the currently used environment, and the user's current role. The currently logged-in user cannot start the jobs created by another user.
  3. For the selected orchestration jobs, click the Start selected button to start the jobs.

To stop orchestration jobs:

  1. Open the Scheduler user interface.

  2. Select the orchestration jobs you want to stop.

    Note:

    You can stop all the jobs that are created by the currently logged-in user, regardless of the environment in which the user is logged in, and role the user is logged in as. The currently logged-in user cannot stop the jobs created by another user.
  3. For the selected orchestration jobs, click the Stop selected button to stop the selected jobs.

    To stop an individual orchestration job, slide the toggle to right in the Started column for selected row.

5.4 Updating to Version 3 Orchestrations

All orchestrations that you create with Orchestrator Studio 9.2.4 use version 3 AIS services and are referred to as version 3 orchestrations.Version 3 AIS services include all version 1 and 2 services available on the AIS, plus additional services that enable you to create an orchestration.

Version 3 orchestrations are compliant with the OpenAPI 2.0 and 3.0 standards. This allows the defined outputs of a version 3 orchestration to be discoverable when using an OpenAPI catalog service. In addition, outputs can now be typed with a version 3 orchestrations, whereas version 1 and 2 outputs must be strings. To comply with the OpenAPI specification, the format of orchestration output has changed in Version 3, particularly the format for arrays. Before upgrading an orchestration to Version 3, review your existing integrations that use Version 1 or Version 2 output and revise them to accept Version 3 output.

See also, "Updating Version 1 Orchestrations to Version 2 Orchestrations" in the JD Edwards EnterpriseOne Orchestrator Guide for Studio Version 8 and Prior.

5.5 Restoring Orchestrations and Orchestration Components

Restore option enables you to reload orchestrations and orchestration components to the state in which they were last saved in the Orchestrator Studio. Use this feature if you do not want to save any modifications that you made.

To restore all files, click the Manage drop-down menu in the Orchestratiosn design page and then click the Restore link.

Each individual orchestration component design page also contains a Restore link in the Manage drop-down menu that you can use to restore an individual component.

5.6 Supported Input Message Formats

The Orchestrator supports two input message formats for orchestrations: a standard JD Edwards EnterpriseOne format and a generic format. The following shows an example of the code for each format.

Standard JD Edwards EnterpriseOne Input Message Format

{
     "inputs": [
         {
             "name": "equipmentNumber",
             "value": "41419"
         },
         {
             "name": "description",
             "value": "test"
         },
         {
             "name": "date",
             "value": "1427774400000"
         },
         {
             "name": "time",
             "value": "12:15:15"
         },
         {
             "name": "temperature",
             "value": "99"
         }
     ]
}

Generic Input Message Format

{
      "equipmentNumber": "41419",
      "description": "test",
      "date": "1427774400000",
      "time": "12:15:15",
      "temperature": "99"
}

5.6.1 Additional Supported Input Message Formats for the Generic Input Format

Additional formats are supported when using the generic input format, as long as the orchestration input values are defined using the full path to the elements used. You may have a deeper JSON structure like this.

{
    "equipmentNumber": "41419",
    "equipementDetail": {
        "type": "thermometer",
        "readingDetail": {
            "temperature": 200,
            "units": "F"
        }
    }
}

To reference the temperature within the orchestration, you can use the full path delimited by periods, for example:

equipmentDetail.readingDetail.temperature

5.6.2 Differences Between Input Message Formats

The following list describes the differences between the input message formats:

  • The iterateOver attribute for the orchestrationStep element is supported only by the standard JD Edwards EnterpriseOne input message format.

  • When using the "detail" form action type with the standard format, it will automatically iterate over all detailInputs and repeatingInputs in order to add multiple rows to a grid. If the generic format is used, only a single grid row can be added.

As shown in the following example, "detailInputs" would correspond to grid data; "repeatingInputs" would correspond to individual rows that contain "inputs" that correspond to columns.

If you have a power form with two grids, you could populate both grids using two "detailInputs" structures with different "name" values that correspond to the different grids. "repeatingInputs" would contain a list of rows and for each row you would define a list of "inputs".

You could also define a Cross Reference orchestration step with iterateOver="GridData" that converts the item value into an EnterpriseOne specific item number. For example, if A123=220 and A124=230, the single orchestration step would convert both.

{
    "inputs": [
        {
            "name": "BranchPlant",
            "value": "30"
        },
        {
            "name": "customer",
            "value": "4242"
        }
    ],
    "detailInputs": [
        {
            "name": "GridData",
            "repeatingInputs": [
                {
                    "inputs": [
                        {
                            "name": "item",
                            "value": "A123"
                        },
                        {
                            "name": "Quantity",
                            "value": "3"
                        }
                    ]
                },
                {
                    "inputs": [
                        {
                            "name": "item",
                            "value": "A124"
                        }
                    ]
                }
            ]
        }
    ]
}

5.7 Orchestration Security Considerations

Before the EnterpriseOne Orchestrator can process an orchestration, authentication of the JD Edwards EnterpriseOne user ID and password must take place. It is the responsibility of the originator of the service request to tell the orchestration about the user. The user's credentials must be supplied in a basic authorization header or in the JSON body of the request. The user must also have authorized access to the EnterpriseOne application in which the resulting transaction takes place. The following code is an example of credentials in the JSON body of the request:

{
                "username":"JDE",
                "password":"JDE",
                "environment":"JDV900",
                "role":"*ALL"
}

The AIS service used with orchestrations is stateless; each call passes credentials to establish a separate EnterpriseOne session. After the transaction is complete, the session closes.

In addition to passing credentials for authentication, you can employ a second level of security for the Orchestrator through whitelisting. Whitelisting enables an initial rudimentary pass/fail check of the incoming device signature against a predefined list of signatures. If a value passed to the Orchestrator is not a valid value included in the orchestration's white list, the Orchestrator rejects the input. For more information, see Creating White Lists in this guide.

5.7.1 Restricting Access to Exposed Orchestrations

If you expose orchestrations for business partners or customers to invoke, it is recommended to use an http proxy to allow access to only the endpoints required to execute the orchestration. Configure the proxy to restrict all endpoints except /orchestrator, /discover, /tokenrequest, and /tokenrequest/logout. This allows external users set up with the proper UDO security to discover and call orchestrations.

5.7.2 How to Maintain a Single Session for Multiple Calls to an Orchestration

You can maintain a single AIS Server session for multiple calls to an orchestration by first performing a token request to get a session token. Otherwise, each call to an orchestration on the AIS Server establishes a separate session, which can decrease AIS Server performance.

When performing a token request, a session is established and the AIS Server returns an AIS token in the response. The token is then used for all orchestration calls in the same session.

The amount of time the session remains open is established through the session lifetime settings in the AIS server. The third party client is responsible for ensuring a valid token is available or re-requesting a new token once a previous token has timed out. If a valid token is not available, the client will receive an error in the response stating the token is invalid.

5.8 Exporting Orchestration Components from the Orchestrator Studio

Caution:

Do not use the Export and Import tools to share orchestration component files with other users. With orchestration components stored as UDOs in EnterpriseOne, the management of orchestration components, including the sharing of orchestration components, the modifying of shared orchestration components, and the promoting of orchestration components to the appropriate AIS Server directory for test or production purposes, is administered through the life cycle management tools in EnterpriseOne.

You can export any of the orchestration component types from the Orchestrator Studio to view the source XML files of the components. This is only recommended for advanced users for troubleshooting purposes or for making manual customizations. The Orchestrator Studio exports the source XML files in a zip file.

The Orchestrator Studio gives you the option to export only the selected orchestration component or the orchestration along with all the components that are associated with it. For example, if you export all components of an orchestration that has a service request component that invokes an orchestration and a rule component associated with it, the zip file will contain XML files for the orchestration, service request along with the orchestration components, and rule.

To export orchestration components:

  1. On a component design page, select Export File from the Manage drop-down menu.

    If you are exporting an orchestration, a dialog box appears in which you can click All or Orchestration Only.

  2. Follow the instructions in the browser to save the zip file to a location on your local machine.

5.9 Importing Orchestration Files in the Orchestrator Studio

Caution:

Do not use the Export and Import tools to share orchestration component files with other users. With orchestration components stored as UDOs in EnterpriseOne, the sharing of orchestration components, and the modifying of shared orchestration components, as well as the promoting of orchestration components to the appropriate AIS Server directory for test or production purposes, is administered through the life cycle management tools in EnterpriseOne.

You might need to import orchestration component XML files that were exported from the Orchestrator Studio for advanced troubleshooting or customization purposes. The Orchestrator Studio Import tool enables you to import individual orchestration XML files or a zip file containing XML files.

Caution:

You cannot import orchestration component files that were exported from the EnterpriseOne Object Management Workbench - Web application. The zip file that is created from an OMW - Web export stores the XML files in a structure that cannot be read by the Orchestrator Studio Import tool.

If importing a zip file that contains orchestration XML files and dependent orchestration component XML files, the zip should contain the following folders with each of the XML files stored in the appropriate folder:

Description of importzip_folders.png follows
Description of the illustration ''importzip_folders.png''

If you import an XML file that has the same name as a current orchestration component (UDO) in the Orchestrator Studio, you have the following options:

  • If the UDO is at a status of "Personal" or "Reserved," you can overwrite the UDO with the XML file.

  • If the UDO is in a "Shared" status, you cannot overwrite it. You can import it as a new UDO with a status of "Personal."

To import files:

  1. On the Orchestrator Studio Home page, click the Import icon.

  2. On the Import page, click the Upload icon.

  3. Locate the orchestration component XML files or zip file that contains the orchestration component files that you want to import.

    After you select the files to import, the Import tool checks the XML files that you selected against the current UDOs in the Orchestrator Studio and displays the options that are available for importing the files.

  4. Review and select the appropriate import option for each file to determine how to proceed with the import. The options are:

    • No update allowed at current status.

      The XML file name is the same as that of an existing component, which has a status of "Pending Approval," so it cannot be overwritten.

    • Select to add or else reserve record and re-import to update.

      A component with the same name exists in the Orchestrator Studio in a "Shared" status. Click the check box if you want to import the file as a new UDO. A new name will be generated for the new component upon import.

      If you want to overwrite the current component in the Orchestrator Studio, do not select the Import check box. Next, change the status of the current component to "Reserved" and reimport the XML file to overwrite the component.

    • File already exists.

      The XML file matches a component that is in a "Personal" or "Reserved" status. Click the check box to import file and overwrite the current component.

    • File is ready to submit.

      The XML file is unique and does not already exist in the Orchestrator Studio. Click the check box to import it.

  5. You can also click the Select All check box to import all the XML files that are available for importing.

  6. Click the Submit button.

    The Orchestrator Studio imports the selected components into the components list on the respective design page.