Defining Reusable Items for Use in Settings
This chapter describes how to define certain reusable items for use as values of settings.
You might also need to define TLS configurations. For information, see InterSystems TLS Guide.
Also see Defining System Default Settings in the next chapter.
Defining Business Partners
InterSystems IRIS provides a way to add additional information to a production to help with the management of a production. A business partner profile is information about an organization or application connected to your InterSystems IRIS system. For each business partner, you can provide information such as the partner name, notes, primary and alternative contacts, and contact details. Defining a profile has no effect on the behavior or running of the production. It simply gives you a means to store more information.
For example, suppose your production talks to ABC Hospital and XYZ Hospital. You can enter profiles for both of these along with contact information. When you configure items that talk to these organizations, you can specify the defined Partner Name for each business host.
The Interoperability > Configure > Business Partners page allows you to view and edit profiles to store information about your business partners for use in your productions.
The page lists any Business Partner Profiles you have already defined and allows you to enter a new profile or edit an existing one in the right pane of the page.
Enter the required unique Partner Name and optional Description and then the following information for a Primary Contact and Alternate Contact:
Mobile Phone Number
Click Save to store this information in the current namespace. When you are configuring productions, this names appears in the Business Partner configuration setting list, which you can choose to use in your production enabling you to categorize business host items in your production by business partner.
To delete a specific business partner profile, select it from the list so it appears in the right pane and then click Remove.
Some remote systems require a username and password to log into that system. A username-password pair is a login credential. InterSystems IRIS permits you to store login credentials in a centralized, secure table; only users with appropriate access to the Management Portal can view and edit this table.
The Interoperability > Configure > Credentials page displays the Credentials table for the current namespace.
Each entry in the Credentials table has an ID which you use as the value of the Credentials setting when configuring business services or business operations for the production. Adding an entry to the Credentials table for a production consists of assigning an ID to a username-password pair. You can also store an informational business partner name with the credential.
The Credentials page displays a list of defined credentials associated with the current namespace. Each row in the table has the following columns:
ID — Unique string that identifies this username-password pair; the name you use in the Credentials setting when configuring a business service or business operation to establish a remote connection.
User name — Username with which to log on to the remote system.
Password — Password corresponding to the logon username.
Business Partner (Optional) — Name of the business partner profile associated with this item.
When editing, you can choose a profile from the list and view its details by clicking the magnifying glass. You can also create or edit a profile by clicking the Business Partners Configuration Page link.
When you select a Credential row, the right pane displays the current settings. If you do not select a row, the right pane shows empty fields for you to create a new credential. Enter values in the fields as outlined in the table description. You have the choice of two actions to perform in the Credentials Viewer:
Click Save to store the updated or new values as a credential and display it in the table.
If you choose to edit a row and change the ID, when you click Save, you must verify that you want to rename the credential.
Click Remove to delete the selected credential.
You cannot undo the Remove operation.
Defining Schedule Specifications
The default scheduling for business hosts is for them to run whenever the production is running. However, a finer control is possible. Not only can you enable and disable business hosts, but the Interoperability > Configure > Production page also provides a Schedule setting for each business host. This is an optional command string that schedules the item to be stopped and started at specific times and on specific days of the week, month, or year. When it is time to start, if the item is enabled, the scheduler starts it; when it is time to stop, if the item is running, the scheduler stops it.
The Interoperability > Configure > Schedule Specs page aids you in creating a string to use in this configuration setting. Once you create a schedule string and give it a name, you can use this string as a value for the Schedule configuration setting.
The Schedule string is a comma-separated list of event specifications. Each event specification has the following format:
Where each item in the event specification, from left to right, has the described values:
|action||START or STOP indicates the desired action|
Once a field is specified as *, all fields to the left of it are also assumed to be *. Thus, if the DD value is *, the MM value is treated as * even if it has a specific numeric value. Similarly, if MM is *, YYYY is treated as *.
|hh:mm:ss||Hour, minute, and second|
|,||Use the comma separator only if there is another event specification after the current one. Do not use it at the end of the Schedule string.|
If you set a schedule specification to be deployable, then the specification can be included when you export the production. When you are exporting the production, select Deployable Settings and select the Ens.Util.Schedule setting.
See the Ens.ScheduleHandler entry in the Class Reference for more information.
If your schedule contains recurring events, the Schedule setting requires both START and STOP actions. If your schedule setting is an absolute one time event, then you need only use the appropriate single START or STOP action. In most cases, Schedule strings should contain both a START and a STOP action.
Some examples of Schedule strings follow:
Start the business host every day at 8 a.m. and stop it every day at 5 p.m.
Stop every year on January 2 at 7 a.m. and start again on January 3 at 7 a.m.
Start every month on the second day of the month at 8 a.m. and stop every month on the tenth day of the month at 8:30 p.m.
Stop every Sunday at 10 a.m. and start every Monday at 8:30 a.m.
Start every third Tuesday at 9 a.m. and stop every third Friday at 4 p.m.
Stop on December 31, 2010 just before midnight.
Start on January 3, 2011 at 6:45 a.m.
The following two strings are equivalent: Start every day at 2 a.m.
Scheduling and Daylight Saving Time
When daylight saving time (DST) begins, clocks skip an hour that day, usually from 2:00 a.m. to 3:00 a.m. Any item you have scheduled that falls into that nonexisting hour takes place at the beginning (which is also the end) of that hour. For example, on the day DST begins, an event scheduled to take place at 2:15 a.m. takes place at 2:00 a.m. (which is also 3:00 a.m.).
When DST ends, an hour of the day repeats, usually from 1:00 a.m. to 2:00 a.m. Any item you have scheduled that falls in that repeated hour takes place only once. Whether the event takes place on the first occurrence of the scheduled time or the second occurrence in the repeated hour depends on the operating system, but it only takes place once. For example, on a Windows system on the day DST ends, an event scheduled to take place at 1:15 a.m. takes place at the second occurrence of 1:15 a.m.
Intended Use and Limitations
The Schedule setting starts and stops production business hosts according to a schedule; it is not a task scheduler. The schedule string defines a square wave in time declaring during what time intervals the item should be running, in between which it should be not be running. InterSystems IRIS cannot prevent scheduled transitions from being interrupted or superseded by other production events.
The scheduler wakes up periodically (it sets its own alarm clock for when any scheduled item next expects a transition) and attempts to start or stop any items that are not currently in the expected state according to their schedule strings. It runs the UpdateProduction() method of the Ens.ScheduleHandler class and checks what event it needs to schedule next.
There are two general classes of things that can prevent transitions from taking place as the schedule string indicates:
The scheduler might be unable to cause the intended state change; that is, the UpdateProduction() method fails to affect the relevant items.
For example, an item could be in a Read timeout or some other busy state that lasts longer than the Update timeout. Another example is a business host the scheduler starts cannot be stopped by the scheduler if the item is in the middle of a synchronous call. The business host must wait for a response to the call before the scheduler stops it.
The scheduler might not be able to wake up at the intended time. Examples of conditions that could cause this: the CPU is busy, a queue builds up of the alarm clock messages for the scheduler, the scheduler is itself disabled or crashed, the production is down, etc. The scheduler is not guaranteed to wake up during any particular interval, and when it does wake up it only looks at the intended state for the current moment, not at any history of when it should have woken up.
Use of the schedule setting is not intended or designed as an event signaling device. It is intended to accommodate planned outages and scheduled intervals of activity or inactivity. If you have events that you must trigger at a particular time or as soon as possible thereafter, InterSystems IRIS provides better alternatives:
You can configure your business service to use an inbound adapter with the implemented OnTask() method where you call the business service. InterSystems IRIS provides classes for many types of inbound adapters. See the Ens.InboundAdapter entry in the Class Reference and the books in the Application Development: Using Adapters and Gateways in Productions set for details.
If you do not want to use an adapter, you can call the business service programmatically and schedule it to run using the System Operations > Task Manager page in the Management Portal. This gives you finer control in situations such as the system being down at 1:00 a.m.
The recommended approach is to configure the business service with Pool Size = 0 and then use the Task Manager to launch a task that calls CreateBusinessService() on it and invokes ProcessInput() on the resulting service instance object. The advantage of calling a business service this way is that you call it at the time you want and it runs only once. If InterSystems IRIS happens to be down at that time, your task can register an error. See the following sections for details: