IT Calendar and Work Mode Management

Work Mode APIs – How to guide

You intend to use the Work Mode Management APIs.

Prerequisites: You have installed and set up FRUN FP01 or above.

Focused Run F01 has two set of APIs for Work Mode Management

  1. Adhoc API: The Adhoc API can be made use to quickly start and stop work mode for a technical component. The Adhoc APIs must be used in the following cases:
    • You want to quickly start/stop work mode on a technical component
    • You want to schedule a work mode for a duration with a time offset
    • You want to create work mode on multiple systems by supplying a short SID
    • You want to create work mode by calling a Web Service.
    • You want to create work mode through an RFC connection
    • You want to abort creating work mode if clashes are found
  2. Work Mode Generic APIs: These APIs can be made use to query, create, delete, edit work modes.
    • You want to do normal CRUD operations
    • You want to specify Start and End time stamps
    • You want to edit an existing work mode

Adhoc Start and Stop APIs for Work Modes

Work Mode management  allows to start and  and stop  Work Modes through RFC enabled function modules. These function modules can also be wrapped into a web service . The user calling these APIs needs to have role SAP_SM_WMM_ALL and authorization to access the relevant customer networks (either network specific role based on SAP_FRN_CNW_ACCESS or SAP_FRN_CNW_ACCESS_ADMIN ).

If you are on FRUN 1.0 FP02, please apply SAP Note 2637360.

 

The Adhoc APIs are described below:

Use Case Function module Description
Start Adhoc Work Modes FM_START_ADHOC_WOR KMODE Schedules a new work mode starting in some seconds  for a certain duration
Stop Adhoc Work Modes  FM_STOP_ADHOC_WORK MODE  Stop an active work mode by setting the end time of  to current time + offset of specified seconds

The FM_START_ADHOC_WORKMODE API

You can use  FM_START_ADHOC_WORKMODES API to create a work Mode after an offset time for a specific duration. All Work Mode types are supported. You can  also schedule multiple Work Modes at the same time by supplying the short SID.  Work Modes can be scheduled on Technical Systems and Technical Instances.

 

Importing Parameters:

Nb Parameter Name Type Info Example
1 IV_CUSTOMER_NETWORK  CHAR255 MANDATORY LOCALNETWORK
2 IV_SYSTEM_ID CHAR255 MANDATORY FBT
3 IV_SYSTEM_TYPE CHAR255 OPTIONAL ABAP
4 IV_INSTANCE_NAME CHAR255 OPTIONAL (only required if the work mode shall be scheduled on instance level, case sensitive) AppServer 00 of FBT on ldcifbt
5 IV_OFFSET_SEC  NUMC04  OPTIONAL 30
6 IV_DURATION_MIN NUMC04  OPTIONAL 60
7 IV_WM_TYPE CHAR40  DEFAULT 010 020
8 IV_TITLE STRING OPTIONALkernel  Test
9 IV_CATEGORY CHAR40  OPTIONAL  002
10 IV_CLASH_ABORT  BOOLEAN  DEFAULT FALSE X
11 IV_APPLY_HOST BOOLEAN  DEFAULT TRUE X
12 IV_APPLY_DB  BOOLEAN  DEFAULT TRUE X
13 IV_DESCIPTION  CHAR255 OPTIONAL Test

Note:

  1. Customer Network Name and System ID are mandatory for all use cases.
  2. Entering the 3 letter System id into field IV_SYSTEM_ID will schedule work mode on all technical systems in the provided customer network that has the same system id (Short SID = FA7 implies FA7~ABAP, FA7~JAVA, FA70001~BOBJ).
  3. Supplying IV_SYSTEM_ID with the up to 8 letter extended System id and filling parameter IV_SYSTEM_TYPE will schedule work mode on the exact technical system. Example: IV_SYSTEM_ID=FA700001 IV_SYSTEM_TYPE=BOBJ.
  4. Supply Short SID, System Type, Instance name to schedule work mode directly on an instance. The supported instance types are ABAP and JAVA technical instances.
  5. The Naming Convention to follow for technical Instance: Use the caption/Display name of the technical instance in the LMDB screen
  6. IV_APPLY_HOST and IV_APPLY_DB are supported only with Technical System use case. They are TRUE by default. 
  7. The Default Work Mode Type is ‘010' – Planned Downtime. 
  8. If you do not specify an Offset, duration or title, these values will be picked from the work mode Customizing table, “WMM_CUSTOM”. If it is not maintained in WMM_CUSTOM and is not supplied during execution, the function module execution will be aborted. 
  9. The Time zone is UTC by default. There is no option to specify time zone as of now. 
  10. The variable IV_CLASH_ABORT takes two values 
    • “X” – True => Stops execution if a clashing work mode is detected 
    • “ “ – False => Does not check for clashes 
  11. The variable IV_APPLY_DB takes two values 
    • “X” – True => Applies work Mode to the DB of the Technical System 
    • “ “ – False => Does not apply to the DB. 
  12. The variable IV_APPLY_HOST takes two values 
    • “X” – True => Applies work mode to the physical or virtual hosts of the Technical System also 
    • “ “ – False => Do not apply to the Host 
  13. Values of context type: a. 020 Host b. 030 Technical Instance c. 060 Technical System d. 080 Database e. 090 Technical Scenario 
  14. Values of Work Mode type: 
    • 10 Planned Downtime 
    • 30 Peak Business Hours 
    • 40 Non-Peak Business Hours 
    • 50 Non-Business Hours 
    • 20 Maintenance 
  15. Values of Work Mode Category: 
    • 001 Hardware Maintenance-General 
    • 002 Hardware Maintenance-Application Server 
    • 003 Hardware Maintenance-Database Server 
    • 004 Hardware Maintenance-Middleware 
    • 005 Hardware Maintenance-Network 
    • 006 Hardware Maintenance 
    • 007 Software Maintenance-General 
    • 008 Software Maintenance-SAP 
    • 009 Software Maintenance-Operating System 
    • 010 Software Maintenance-Database 
    • 011 Software Maintenance-Other Component 
    • 012 General 
  16. System Types: 
    • 'ABAP' Application Server ABAP 
    • 'JAVA' Application Server JAVA 
    • 'HANADB' SAP HANA Database 
    • 'SUP' SAP Mobile Platform 
    • 'MDM' SAP NetWeaver Master Data Management Server 
    • 'TREX' TREX System 
    • 'UNSPECIFIC' Unspecific Standalone Application System 
    • 'BOBJ' SAP Business Object Cluster 
    • 'DIAGNAGENT' Diagnostics Agent 
    • 'ATC' Apache Tomcat Server 
    • 'CLOUD_CONN' SAP Cloud Platform Cloud Connector 
    • 'LIVE_CACHE' SAP LiveCache 
    • 'MSIISINST' Microsoft Internet Information Services 
    • 'MS_.NET' .NET System 
    • 'WEBDISP' SAP Web Dispatcher 
    • 'WEBSPHERE' IBM WebSphere Application Server 
    • 'IS_EM' Introscope Enterprise Manager (Standalone) 
    • 'IS_MOM' Introscope Enterprise Manager (Cluster) 
    • 'UNSP3TIER' Unspecific 3-Tier System 
    • 'UNSPAPP' Unspecific Cluster System

The FM_STOP_ADHOC_WORKMODE API

The FM_STOP_ADHOC_WORKMODE API is used to stop an ongoing work mode after an offset time. The User is enabled to stop work modes on Technical Systems and Technical Instances. The use cases are same as that in Start Adhoc and all the rules apply here too.

Importing Parameter:

Nb Parameter Name Type Info Example
1 IV_CUSTOMER_NETWORK CHAR255 MANDATORY LOCALNETWORK
2 IV_SYSTEM_ID  CHAR255 MANDATORY FBT 
3 IV_SYSTEM_TYPE CHAR255 OPTIONAL  ABAP
4 IV_INSTANCE_NAME CHAR255 OPTIONAL  AppServer 00 of FBT on ldcifbt
5 IV_OFFSET_SEC TIMESTAMP OPTIONAL  30
6 IV_WM_TYPE CHAR40 DEFAULT 010 60
7 IV_ADHOC_ONLY BOOLEAN  OPTIONAL  X

Note:

  1. The behavior of the input parameters conforms to the FM_START_ADHOC_WORKMODE.
  2. The variable IV_ADHOC_ONLY takes two values
    • “X” – True => Stops only the work mode created by Adhoc API
    • “ “ – False => Stops all current work modes
  3. IV_WM_TYPE if specified stops only the work modes of that type. The default value is ‘010' i.e., Planned Downtime.
  4. When testing these function modules from transaction SE37 please set the flag Uppercase/Lowercase

 

 

Work Mode Generic APIs

These APIs are part of CL_WMM_API class. Please open transaction se24 and navigate to CL_WMM_API to use these. These APIs can be wrapped in a Function Module to expose it. 

Use Case API Class Method Parameters / Description
Retrieve Workmodes GET_ALL_WMS_FOR_CON TEXT_IDS Specify the Long SID and type of the context and time range and the work mode details will be returned 
Create Workmodes  CREATE_WM_FOR_OLD_I NTERFACE  Specify the Long SID, type of the context and other work mode details and the created work mode guid will be returned 
Edit Workmodes EDIT_WORKMODE Specify the work mode GUID and other work mode details 
Delete Workmodes DELETE_WORKMODE  Specify the work mode GUID to be deleted.

The GET_ALL_WMS_FOR_CONTEXT_IDS API

The GET_ALL_WMS_FOR_CONTEXT_IDS API is used to retrieve the work modes. It retrieves all the work modes between the timestamps that are specified. The timestamp can be provided in the same time zone as it was provided at the time of creation. In case of overlapping work modes, all the work modes are retrieved irrespective of the work mode priority and time of creation. Moreover, the IV_CURRENT flag can be used to retrieve the active/inactive work modes.

Importing Parameter: 

Nb Parameter Name Type Example
1 IT_CONTEXTS CL_WMM_API=>TY_T_CONTEXTS {{FA7~ABAP, 060}, {FBT~ABAP, 060}} 
2 IV_CURRENT BOOLEAN X
3 IV_START_TIMESTAMP TIMESTAMP  20170802000000
4 IV_END_TIMESTAMP  TIMESTAMP  20170803000000

Exporting Parameter:

ET_WORKMODES TYPE CL_WMM_API=>TY_T_WORKMODE_DATA

Note:

  1. The variable IV_CURRENT takes three values u. “X” – True => Retrieves active services alone v. “-“ – False => Retrieves all services. w. “ ” – Space => Unknown i.e., no filter is set
  2. IT_CONTEXTS is a table which accepts two values, MO_NAME and MO_TYPE.
  3. All the importing parameters are mandatory.

 

The CREATE_WM_FOR_OLD_INTERFACE API

It is used to create a new work mode.

Importing Parameter: 

Nb Parameter Name Type Example
1 IV_MO_NAME  CHAR255 FA7~HANADB
2 IV_MO_TYPE WMM_D_MO_TYPE 060
3 IV_TYPE  CHAR40  020
4 IV_CATEGORY CHAR40 (OPTIONAL) 004
5 IV_START  TZNTSTMPS  20170802000000
6 IV_END TZNTSTMPS  20170803000000
7 IV_TITLE STRING Test
8 IV_TIME_ZONE DT_ZONE UTC
9 IV_DESCRIPTION STRING (OPTIONAL)  Test

Exporting Parameters:

  1. EV_WORKMODE_GUID TYPE CHAR32
  2. ET_ERROR_MESSAGES TYPE CL_WMM_API=>TY_T_MSG

Exceptions: 1. CX_WORKMODE_EXCEPTION for authorization or other errors.

Note:

  1. The Time zone is used to convert the timestamps to UTC. The user may enter in the timestamp in any time zone.
  2. The exporting parameter EV_WMM_GUID can be supplied to the DELETE_WORKMODE or EDIT_WORKMODE to delete/edit the work mode.
  3. Overlapping work modes are possible. User is not notified in case of one. The API creates a new work mode and returns a new EV_WORKMODE_GUID. An overlapping work mode with a lesser priority is also accepted.
  4. This API creates a work mode while the FM_GET_WORKMODES retrieves the existing work modes. 

 

The EDIT_WORKMODE API

It can be used to edit a previously created work mode. The user may edit title, category, start, end, time zone, description. If the user is not planning to change a mandatory field you are supposed to provide the old value again. The Category and Description fields are made optional whereas the title, start time, end time and time zone are a mandate.

Importing parameters: 

Nb Parameter Name Type Example
1 IV_WMM_GUID CHAR32 AD0560342341890923 849235783ABT12 
2 IV_TITLE CHAR120 Test
3 IV_CATEGORY WMM_D_CATEGORY 002
4 IV_START  TZNTSTMPS 20170802000000
5 IV_END  TZNTSTMPS  20170803000000
6 IV_TIMEZONE TZNZONE INDIA
7 IV_DESCRIPTION STRING Test

Exporting parameters:

  1. EV_ERROR TYPE BOOLEAN
  2. ET_ERROR_MESSAGES TYPE CL_WMM_API=>TY_T_MSG

Exceptions:

CX_WORKMODE_EXCEPTION for authorization or other errors.

Note: IV_WMM_GUID is the work mode guid EV_WORKMODE_GUID that is returned by CREATE_WM_FOR_OLD_INTERFACE API.

The DELETE_WORKMODE API

The DELETE_WORKMODE API can be used to delete a previously created work mode. Importing parameters IV_WMM_GUID TYPE CHAR32

Exporting parameters:

  1. EV_ERROR TYPE BOOLEAN
  2. ET_MESSAGES TYPE CL_WMM_API=>TY_T_MSG

Exceptions: 1. CX_WORKMODE_EXCEPTION for authorization or other errors.

Note: IV_WMM_GUID is the work mode guid EV_WORKMODE_GUID that is returned by CREATE_WM_FOR_OLD_INTERFACE API.

 

Code Snippets for Generic API Consumption 

How To Define a Webservice for the Adhoc Workmode APIs

The Adhoc APIs are RFC enabled and can thus be called via RFC. If you would like to achieve that external systems can start and stop work modes (e.g. planned downtimes) by web services, you need to create the corresponding web services as follows:

  1. Call transaction SE80. Select Function group FG_EXTERNAL_APIS.
  2. Right click on FM_START_ADHOC_WORKMODE. Select Create Enterprise Service.
  3. Enter a name and a description for the service definition. 
  4. Choose the Authentication method which suits your needs

  1. Define package or request or choose local object. Activate the Service definition .
  2. Call transaction SOAMANAGER web service configuration -> search for new service definition. Select the service definition.
  3. Select Create Service.
  4. Select Provider Security as per your requirements. Press Finish.

Repeat the steps above for function module “FM_STOP_ADHOC_WORKMODE”.