l o g i c b u i l d e r g u i d e - epmware.com logic builder guide.pdf · l o g i c bu i l d e r g...

Logic Builder Guide EPMWARE ®

EPMWARE, Inc. Updated: Feb, 2018

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of EPMware Inc. EPMware, Inc. may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from EPMware, Inc., the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. © 2017 EPMWARE, Inc. All rights reserved. www.epmware.com | 408-614-0442 EPMWARE is a registered trademark of EPMWARE, Inc. in the United States and/or other countries. All other trademarks are property of their respective owners.

Logic Builder Guide 1

EPMWARE ® 1 Version 1.0.15 1

Introduction 6

Logic Builder Provisioning 7

How to access Logic Builder 7

Create Logic Builder Scripts 8

Logic Builder Script 10 Script Structure 10 Common Output Parameters 11 Script Types 11

Deployment Pre/Post Tasks 11 Input Parameters 12 Output Parameters 13

Dimension Mapping 13 Request Action: Create Member 13

Input Parameters 14 Output Parameters 15

Request Action: Rename Member 15 Input Parameters 15 Output Parameters 16

Request Action: Edit Properties, Remove Shared Member, Delete Member 17 Input Parameters 17 Output Parameters 18

Request Action: Reorder Children 18 Input Parameters 18 Output Parameters 19

Request Action: Move Member 19 Input Parameters 20 Output Parameters 21

Request Action: Insert Shared Member 21 Input Parameters 21 Output Parameters 23

ERP Interface Tasks 23

Input Parameters 23 Output Parameters 24

Pre Hierarchy Actions 24 Input Parameters 24 Output Parameters 25

Post Hierarchy Actions 25 Input Parameters 25 Output Parameters 26

Property Derivations 27 Input Parameters 27 Output Parameters 27

Property Mapping 28 Input Parameters 28 Output Parameters 29

Property Validations 29 Input Parameters 29 Output Parameters 30

Workflow Custom Task 30 Input Parameters 30 Output Parameters 31

Logic Builder API Library 31 Database Views 31

EW_APPS_V 31 EW_APP_DIMENSIONS_V 31 EW_REQUEST_LINE_MEMBERS_V 32 EW_MEMBERS_V 34 EW_HIERARCHY_MEMBERS_V 34

Record types 35 EW_LB_API.G_WF_TASK_REC 35

Database Functions 36 Logic Builder API Functions 36

FUNCTION get_new_member_prop_value 36 FUNCTION get_member_prop_value 37 FUNCTION get_parent_prop_value 37 FUNCTION get_member_prop_value 37 FUNCTION is_numeric 37 FUNCTION is_leaf 38 FUNCTION get_descendants_count 38

FUNCTION get_descendants_count (Overloaded) 38 PROCEDURE update_member_prop 38 FUNCTION get_req_attrib 39 FUNCTION get_req_attrib (Overloaded) 39

Email API Functions 40 Send Email (no Template) 40 Send Email (Email Template ID) 40 Send Email (Email Template Name) 41 Email Body Tables 41

Request API Functions 42 Get Request Header Information 42 Insert note in the request 43 Check if user can perform specific action on the given request 43 Check if the user need to perform any action on the given request id 44 Check if the user can perform specific action on the Dimension and in a request 44 Validate Insert Member Action 45 Get Request Line Record 46 Get Request Status 46 Get Request Status Code 47 Get Request Header Workflow Status 47 Get Request Line Workflow Status 48 Get Current Workflow stage name for given Request ID 48 Get Group Name on Request is pending action from 48 Execute Request Header action 48 Execute Request Line Action 49 Get Request Lines Count 49 Create Request Header Record 49 Create Request Line for Delete Member Action 50 Create Request Line for Remove Shared Member Action 50 Create Request Line for Rename Member Action 51 Create Request Line for New Member Action 51 Create Request Line for Move Member Action 51 Create Request Line for Reorder Children Action 52 Create Request Line for Edit Properties Action 52 Create Request Line for Insert Shared Member Action 53 Send Reminder Email 53 Hierarchy Acton code List 53

Security API Functions 54

Get Group names separated by comma in which contains given user 54 Check if the user is in given group name or not 54 Check if the user is Active or Disabled 55 Get Access Type for the Deployment module 55 Get Access Type for the Workflow module 55 Check if user has Read or Write access to Workflow module 55 Check if user has Read or Write access to Deployment module 55 Check whether user has access to the App dimension or not. 55 Check whether user has access to the Security Class or not 55 Check if user has given role or not 56 Create new User 56 Enable User 57 Disable User 57 Create New Group 57 Enable Group 57 Disable Group 57 Assign user to Group 57 Unassign user to Group 57

Agent API Functions 57 API Parameters 59 Remote Custom Script requirements 60

Examples 60 Pre/Post Deployment Tasks 61

Introduction Logic Builder Module allows users to build custom logic in various modules within

EPMWARE to augment customer requirements such as property validations, custom tasks in workflow etc. Logic Builder utilizes native Oracle PL/SQL language and logic resides in EPMWARE database. You can develop custom packages, procedures and functions and reference them in the application or using script text box pass the script in this module directly too.

Logic Builder Provisioning Using Security Provisioning as shown below enable “Logic” module checkbox to the

appropriate group so that users of that group can create logic scripts for various types.

How to access Logic Builder In order to access logic builder module, you have to be provisioned with “Logic” module.

If you are provisioned then you should be able to see the logic builder menu item. Click on the Scripts menu item to open the Logic Builder page.

Create Logic Builder Scripts In the scripts page, click on + sign ( ) to create new logic script. To edit the existing

script use right click menu and select “Edit Properties” menu item. Following popup shows up where you can configure script name and its type.

1. Script Name: Enter user friendly name of the script. This name has to be unique among all script types and can be upto 50 characters long.

2. Description: This is an optional field. Enter description of the logic script. 3. Script Type: Select one of the script type from the drop down list. See table below for

script type and its purpose. 4. DB Function Name: This is an optional field. You can specify standalone stored Oracle

Procedure name OR stored packaged procedure name here. If this field is populated then Script Editor gets disabled for this record.

5. Enabled: This checkbox enables or disables this script. If the script is disabled then it will not be invoked.

Script Type Purpose Referenced in Page

Deployment Tasks Used in Pre and Post Deployment Tasks

Deployment Page

Dimension Mapping Used during creation of request lines for mapped dimensions

Configuration -> Dimension -> Mapping page

ERP Interface Tasks Used in Pre and Post ERP Import execution tasks

ERP Import -> Builder page

Post Hierarchy Actions Used to execute custom logic after any hierarchy action on the member in requests

Property Derivations Used to derive property values Configuration -> Property -> Derivations

Property Mapping Used to map property values between mapped dimensions

Configuration -> Property -> Mapping

Property Validations Used to perform property validation

Configuration -> Property -> Validations

Workflow Custom Task Used to perform custom task in workflow (custom type of task)

Workflow -> Tasks

Logic Builder Script Script associated with the logic builder can be entered in the application in one of the

two ways. One option is to create stored database procedure (or packaged procedure) and refer it in the script record in the DB Function name field. Other option is to enter script in the script editor as shown below.

When you click on “Save” icon it automatically validates this script for any syntax errors. Logic errors within the script will not be detected till you run this script in the request for the conditions that could invoke this logic script. For example, if the script is used to validate property value then you will need to create request for that action on dimensions that could trigger this property validations.

Script Structure Main API for Logic builder scripts is EW_LB_API package. You can refer to this

package’s specifications for its input parameters as well as output parameters as expected by various type of logic scripts. Logic Builder expects status and message variables for all types of scripts in order to determine whether script completed successfully OR errored out.

It is highly recommended to handle exceptions in your code and use “EW_DEBUG.LOG” procedure to record debug messages in the centralized debug table. (Debug messages can be downloaded from admin report).

Following section will provide details on each logic builder script type, its usage, input/output parameters and examples.

Common Output Parameters Following table shows fixed output variables and values that are always expected from

the Logic Builder Script. These output variables must be set by logic script regardless of script type.

Parameter Name Package variable Description

Status ew_lb_api.g_status Status Values are either ‘S’ for Success or ‘E’ for Error. Alternatively use following method to set values in your code. ew_lb_api.g_status := ew_lb_api.g_success; OR ew_lb_api.g_status := ew_lb_api.g_error; Set the value appropriately based on your logic script requirements. If Error code is passed then workflow will halt the progress of the request and notify requestor. Set the value using

Message ew_lb_api.g_message Pass Error Message if the status is Error.

Script Types

Deployment Pre/Post Tasks Use this logic script type to run custom tasks before deployment starts or after

deployment completes (regardless of status being success, failed or partial). Logi scripts of the deployment type can be referred in Deployment Manager as shown below.

Input Parameters Following table shows parameters passed to the Logic Builder API that custom script

can leverage within their script.


Deployment ID ew_lb_api.g_deployment_id

This is the deployment id being executed. Using this ID further information such requests, request line ids being deployed can be fetched from other source tables. This ID can be used in Deployment Monitor to review deployment files, requests, log files etc. See below screenshot for where this ID is being referenced.

Deployment Stage ew_lb_api.g_dep_stage PRE or POST

Deployment Status ew_lb_api.g_dep_statu Fore PRE Stage

s ● Pending For POST Stage

● Completed ● Failed ● Partial

Deployment Configuration Name

ew_lb_api.g_dep_config_name

Name of the deployment

Deployment related Request Lines

ew_lb_api.g_dep_req_lines_list

This is a collection of records from request line members view which are part of this deployment. See API Library for the database view EW_REQUEST_LINE_MEMBERS_V

Output Parameters Following table shows output variables and values are expected from the Logic Builder

Script. See Common Output Parameters. No additional output parameters are required for this

script type.

Dimension Mapping

Dimension mapping means members of a dimension in one application are synchronized with members of the other dimension in the mapped application. Synchronization occurs whenever an action is taken in one dimension in a request and you want similar action (or ignore the action) to the mapped dimensions using logic script. Logic Builder will provide input parameters to your script for each request action so that your script can take appropriate action and provide expected output parameters for the mapped dimension.

Request Action: Create Member Whenever New Member action is being taken on the source dimension, dimension mapping logic script gets invoked provided dimensions are mapped via Logic Script. Logic Script needs

to provide New Member name for the mapped dimension as well as under which parent member as Child Member OR under a parent member as sibling member.




Action Code ew_lb_api.g_action_code

CMC -> Create Member as Child CMS -> Create Member as Sibling

Action Name ew_lb_api.g_action_name

Create Member

Application Name ew_lb_api.g_app_name Source Application Name on which action is being taken

Dimension Name ew_lb_api.g_dim_name Source Dimension Name on which action is being taken

Mapped Application Name

ew_lb_api.g_mapped_app_name

Mapped Application Name on which action needs to be taken

Mapped Dimension Name

ew_lb_api.g_mapped_dim_name

Mapped Dimension Name on which action needs to be taken

Parent Member Name

ew_lb_api.g_parent_member_name

Source Dimension’s Parent Member Name on which new member action is being taken

Member Name ew_lb_api.g_member_name

Source Dimension’s Member Name on which new member action is being taken,

Hierarchy ID ew_lb_api.g_hierarchy_id

Source Dimension’s Hierarchy ID (Hierarchy ID is Primary key in ew_hierarchy table that holds Parent Member and its child member ids)

New Member Name

ew_lb_api.g_new_member_name

New Member in the source dimension

New Member Flag ew_lb_api.g_new_member_flag

Y

Output Parameters

See Common Output Parameters. See below for additional output parameters that are required for this script type.


Ignore Flag ew_lb_api.g_out_ignore_flag

Y or N to indicate whether action need to be ignored in the mapped dimension or not.

Parent Member Name

ew_lb_api.g_out_parent_member_name

Parent Member Name from the mapped dimension

Member Name ew_lb_api.g_out_member_name

Member Name from the mapped dimension

New Member Name

ew_lb_api.g_out_new_member_name

New Member name for the mapped dimension

Note: Parent Member Name and Member Name of mapped dimension determines

where the new member name will be created in that mapped dimension. If the Action Code is CMS (Crate Member as Sibling) then New Member will be created

after the Member Name under the Parent Member Name. If the Action Code is CMC (Crate Member as Child) then New Member will be created

under the Member Name.

Request Action: Rename Member Whenever Rename Member action is being taken on the source dimension, dimension mapping logic script gets invoked provided dimensions are mapped via Logic Script. Logic Script needs to provide New Member name (Renamed) as well as node information (Member name and Parent Member name) for the mapped dimension.





‘RM’


Rename Member









Parent Member Name



Orig Member Name

ew_lb_api.g_member_name

Source Dimension’s Member Name on which action is being taken

New Member Name


Renamed member name



Output Parameters





Parent Member Name



Member Name ew_lb_api.g_out_mem Member Name from the mapped dimension

ber_name that will be renamed

Renamed Member Name

ew_lb_api.g_out_new_member_name

Renamed Member Name for the Mapped dimension

Request Action: Edit Properties, Remove Shared Member, Delete Member Whenever one of the following actions is being taken on the source dimension, dimension mapping logic script gets invoked provided dimensions are mapped via Logic Script. Logic Script needs to provide Member name and Parent Member name for the mapped dimension.

● Edit Properties ● Remove Shared Member ● Delete Member





‘P’ -> Edit Properties ‘RSM’ -> Remove Shared Member ‘DM’ -> Delete Member


One of the following actions. Edit Properties Remove Shared Member Delete Member









Parent Member Name


Source Dimension’s Parent Member Name on which action is being taken





Output Parameters





Parent Member Name





Request Action: Reorder Children Whenever Reorder Member action is being taken on the source dimension, dimension mapping logic script gets invoked provided dimensions are mapped via Logic Script. Logic Script needs to provide node information (Member name and Parent Member name) for the mapped dimension.





‘RM’


Rename Member









Parent Member Name





Output Parameters





Parent Member Name




Member Name from the mapped dimension that will be renamed

Request Action: Move Member

Whenever Move member action is being taken on the source dimension, dimension mapping logic script gets invoked provided dimensions are mapped via Logic Script. Logic Script needs to provide Member name and Parent Member name for the mapped dimension as well as moved to parent member name for the mapped dimension.





ZC


Move Member









Parent Member Name




Source Dimension’s Member Name on which action is being taken,



Moved to Member Name

ew_lb_api.g_moved_to_member_name

New Parent Member where the source member is moved to

Output Parameters





Parent Member Name






g_out_moved_to_member_name

New Parent Member name where the member will be moved to for the mapped dimension

Request Action: Insert Shared Member Whenever Insert Shared member action is being taken on the source dimension, dimension mapping logic script gets invoked provided dimensions are mapped via Logic Script. Logic Script needs to provide Member name and Parent Member name for the mapped dimension. As this action allows multiple members to inserted in single action, logic script need to provide list of mapped members in the list format as well.





ISMC -> Insert Shared Member as Child ISMS -> Insert Shared Member as Sibling


Insert Shared Member









Parent Member Name




Source Dimension’s Member Name on which action is being taken,



Shared Member Names List

ew_lb_api.g_shared_members_tbl

This is a PL/SQL collection (table) with the list of Member names from source dimension which will get Shared instances. If the action is Insert Shared Member as Child then shared instances will be created under Member Name. Shared instances will be created as the last member under the parent member. If the action is Insert Shared Member as Sibling then shared instances will be created under Parent Member and after the Member name.

ew_lb_api.g_shared_members_tbl is TABLE type collection. Type is as mentioned below.

TYPE g_members_tbl_t IS TABLE OF ew_members.member_name%TYPE

INDEX BY BINARY_INTEGER;

Output Parameters





Parent Member Name





Shared Members List

ew_lb_api.g_out_shared_members_tbl

Mapped Members from the Shared Dimension which will get shared instance

ew_lb_api.g_out_shared_members_tbl is TABLE type collection. Type is as mentioned below.

TYPE g_members_tbl_t IS TABLE OF ew_members.member_name%TYPE

INDEX BY BINARY_INTEGER;

ERP Interface Tasks There are two types of ERP Interface tasks (Pre Import and Post Import) that can be

developed for your ERP Import module. Pre Import tasks are executed whenever new records for the ERP interface are found

and before they are processed by ERP Import execution. Post Import tasks are executed after records are processed for the ERP Interface.

Input Parameters


ERP Interface configuration name

ew_lb_api.g_if_config_name

ERP Interface configuration name for which Pre Task or Post task will be executed.

ERP Interface Execution ID

ew_lb_api.g_if_exec_id This is the unique execution if whenever records from the interface lines tables are found and processed. You can view this ID in ERP monitor screen. Note: Using this ID records that are being processed can be accessed in ew_if_lines (or table associated with the ERP configuration) table.

Execution Stage ew_lb_api.g_if_stage PRE or POST

Output Parameters See Common Output Parameters.

Pre Hierarchy Actions Pre Hierarchy Actions are used when custom logic need to be invoked before an action

is executed on the dimension and request line is created. Currently, Pre hierarchy action if created will be executed after each action on any

dimension gets executed. A condition may be required in the script to limit the scope of execution by application or dimension depending on requirements.

Input Parameters

Following table shows parameters passed to the Logic Builder API that custom script can leverage within their script.



For example ‘RM’


For Example Rename Member



User ID ew_lb_api.g_user_id Internal User ID

Request ID ew_lb_api.g_request_id Request ID on which this post hierarchy action will be executed


Member Name on which hierarchy action is being initiated

Parent Member Name


Parent Member Name on which hierarchy action is being initiated

Previous Sibling Member Name

ew_lb_api.g_prev_sibling_member_name

Previous Sibling Member Name on which hierarchy action is being initiated

Moved from Member Name

ew_lb_api.g_moved_from_member_name

Member Name from which the member is moved from if the action is Move Member



Member Name where the member is moved to if the action is Move Member

Output Parameters See Common Output Parameters. No additional output parameters that are required for

this script type.

Post Hierarchy Actions Post Hierarchy Actions are used when custom logic need to be invoked after an action

has been successfully been executed on the dimension and request line is created. Currently, Post hierarchy action if created will be executed after each action on any

dimension gets executed. A condition may be required in the script to limit the scope of execution by application or dimension depending on requirements.

Input Parameters




For example ‘RM’


For Example, Rename Member



User ID ew_lb_api.g_user_id Internal User ID

Request ID ew_lb_api.g_request_id Request ID on which this post hierarchy action will be executed

Request Line ID ew_lb_api.g_request_line_id

Request Line ID


Member Name of the request line

Parent Member Name


Parent Member of the request line


ew_lb_api.g_prev_sibling_member_name


Moved from Member Name

ew_lb_api.g_moved_from_member_name

Member Name from which the member is moved from if the action is Move Member



Member Name where the member is moved to if the action is Move Member

Output Parameters See Common Output Parameters. No additional output parameters that are required for

this script type.

Property Derivations


can leverage within their script. Property Derivation scripts are invoked whenever new member is being created OR

properties of existing member are being updated.


Application Name ew_lb_api.g_app_name Application Name on which action is being taken

Dimension Name ew_lb_api.g_dim_name Dimension Name on which action is being taken

Parent Member Name


Source Dimension’s Parent Member Name on which new member action or edit properties is being taken


Source Dimension’s Member Name on which new member action or edit properties is being taken




Y when New member action is called N when Properties are being edited afterwards for the new member or an existing member

Output Parameters See Common Output Parameters. See below for additional output parameters that are

required for this script type.


Property Value ew_lb_api.g_out_prop_value

Derived Property Value

Property Mapping

Input Parameters











Parent Member Name





Mapped Parent Member Name

ew_lb_api.g_mapped_parent_member_name


Mapped Member Name

ew_lb_api.g_mapped_member_name


Source Property Label

ew_lb_api.g_prop_label Property Label from the Source Dimension

Source Property Value

ew_lb_api.g_prop_value

Property Value for member in the source dimension

Mapped Property Label

ew_lb_api.g_mapped_prop_label

Property Label of the mapped dimension

Output Parameters See Common Output Parameters. See below for additional output parameters that are

required for this script type.


Mapped Property Value

ew_lb_api.g_out_prop_value

Property Value for the mapped dimension



Property Validations


can leverage within their script. This script type is invoked whenever property changes are saved and if the property

validation script is assigned to that property.



One of the following action code. CMC -> Create Member as Child CMS -> Create Member as Sibling RM -> Rename Member P -> Edit Properties


One of the following action. Create Member Rename Member Edit Properties

Application Name ew_lb_api.g_app_name Application Name on which action is being taken

Dimension Name ew_lb_api.g_dim_name Dimension Name on which action is being taken

Parent Member ew_lb_api.g_parent_m Source Dimension’s Parent Member Name

Name ember_name on which new member action is being taken


Source Dimension’s Member Name on which new member action is being taken,



New Member Name


New Member Name if the property validation is for Member Name. Otherwise this parameter is NULL


Y is the action is Create Member OR Rename Member (Rename Member goes through the same validation as new member name being created for Member Name Property Validation)

Array Member Name

ew_lb_api.g_array_member_name

If the Property is Array Type (For example Alias) then this parameter holds Member name from the associated dimension (such as Alias dimension member such as Default, English, French, etc.)


Workflow Custom Task




Request ID ew_lb_api.g_request_id Request ID of the workflow execution

Workflow Task Record

ew_lb_api.g_wf_task_rec

Record type variable which provides information such as workflow Stage, Task etc. See API Library for record columns.


Logic Builder API Library

Database Views

EW_APPS_V This view holds information about applications setup in EPMWARE application. Key columns are as mentioned below.

Column Name Meaning

APP_ID Primary key identifier of the App Table

NAME Application Name

TARGET_APP_NAME Target Application Name

ENABLED_FLAG Y/N to indicate whether application is enabled or disabled

USER_NAME Application User Name

PASSWORD Encrypted Password

EW_APP_DIMENSIONS_V

This table holds information about dimensions in EPMWARE application. Key columns are as mentioned below.

Column Name Meaning

APP_DIMENSION_ID Primary key identifier of the Dimensions Table

APP_ID Application ID

APP_NAME Application Name


ENABLED_FLAG Y/N to indicate whether dimension is enabled or disabled

APP_ENABLED_FLAG Y/N to indicate whether application is enabled or disabled

APP_TYPE Internal code for Application Type

DIM_CLASS_NAME Dimension Class Name

EW_REQUEST_LINE_MEMBERS_V This view provides request line and its dimension members data. Key columns are as

mentioned below.

Column Name Meaning

ACTION_CODE Internal Code Request Line Actions

ACTION_NAME Action Name such as “Create Member”, “Edit Properties”.



CHILDLESS_PARENT_MEMBER_NAME

Parent Member Name if it is Childless

DEPLOY_DATE Deploy Date of the request line

DIM_CLASS_NAME Dimension Class Name

DIM_NAME Dimension Name

HIERARCHY_ID Primary identifier of the table that stores nodes.

LINE_NUM Request Line #

MEMBER_ALIAS Primary Alias of the member

MEMBER_ID Member ID. Primary identifier of the table that stores members

MEMBER_NAME Member Name

MOVED_FROM_MEMBER_ID Moved from the Member ID if the line action is Move Member

MOVED_FROM_MEMBER_NAME Moved from the Member Name if the line action is Move Member

ORIG_MEMBER_NAME Original Member name if the line action is Rename Member

PARENT_MEMBER_ID Parent Member id. Primary identifier of the table that stores members

PARENT_MEMBER_NAME Parent Member Name

PREV_SIBLING_MEMBER_NAME Previous Sibling Member Name

PREV_SIBLING_PRIMARY_FLAG Y/N flag to indicate whether previous member is a primary member or not

PRIMARY_FLAG Y/N flag to indicate whether member is a primary instance or not

RELATED_LINE_ID Request line id to which this line is related to

REQUEST_ID Request ID

REQUEST_LINE_ID Request Line id

REQUEST_LINE_MEMBER_ID Request Line Member ID

SORT_ORDER Sort order of the member

STATUS Status of the request line


EW_MEMBERS_V This view provides members data. Key columns are as mentioned below.

Column Name Meaning

APP_NAME Application Name

DIM_NAME Dimension Name



MEMBER_ID Primary identifier for the member

MEMBER_NAME Member Name. Member name has to be unique within the dimension.

STATUS Status of the Member A -> Active (No pending activity) W -> Work in Progress (Some pending activity)

ROOT_FLAG Y/N flag to indicate whether the member is a root member of the dimension

CREATION_DATE Date member was created

LAST_UPDATE_DATE Last update date on the member

EW_HIERARCHY_MEMBERS_V This view provides nodes data. Key columns are as mentioned below. Node is a

combination of member id and parent member id combination. This combination is a unique combination.

Column Name Meaning

HIERARCHY_ID Primary identifier of the view


MEMBER_ID Member ID. Primary identifier of the table that stores

members

MEMBER_NAME Member Name

MEMBER_STATUS Status of the Member A -> Active (No pending activity) W -> Work in Progress (Some pending activity)

HIERARCHY_STATUS Status of the Member A -> Active (No pending activity) W -> Work in Progress (Some pending activity)

PARENT_MEMBER_ID Parent Member id

PARENT_MEMBER_NAME Parent Member Name

PARENT_ROOT_FLAG Y/N flag to indicate whether the member is a root member of the dimension

SORT_ORDER Sort order of the member within its parent member

PRIMARY_FLAG Y/N flag to indicate whether member is a primary instance under parent member. Y -> Primary N -> Shared Instance

Record types

EW_LB_API.G_WF_TASK_REC Ew_lb_api.g_wf_task_rec is based on database view EW_WF_STAGE_TASKS_C_V. Columns of this record type are mentioned below.

1. ACTION 2. ACTION_CODE 3. CYCLE_STATUS 4. DESCRIPTION 5. EMAIL_TEMPLATE 6. EMAIL_TEMPLATE_ID 7. ENFORCED_FLAG 8. FREEZE_FLAG 9. GROUP_ID

10. GROUP_NAME 11. LB_SCRIPT_ID 12. METADATA_FLAG 13. NUM_OF_APPROVALS 14. PRIORITY_CODE 15. REQUEST_ID 16. SCRIPTS_FLAG 17. STAGE_NAME 18. STAGE_NUM 19. STAGE_STATUS 20. STAGE_TASK_MESSAGE 21. STAGE_TASK_SEQ_NUM 22. STAGE_TASK_STATUS 23. STAGE_TASK_STATUS_MEANING 24. TASK_ACTION_CODE 25. TASK_DESCRIPTION 26. TASK_NAME 27. WF_CYCLE_ID 28. WF_ID 29. WF_STAGE_ID 30. WF_STAGE_TASK_ID 31. WF_TASK_ID 32. WORKFLOW_NAME

Database Functions

Logic Builder API Functions Logic Builder API Package Specification provides list of functions as mentioned below that can be used for building logic for your custom solution. These functions can be referred as ew_lb_api.<Function Name>.. Package: EW_LB_API

FUNCTION get_new_member_prop_value

-- Return Member property value for current hierarchy for which

-- logic script is being invoked

FUNCTION get_new_member_prop_value (p_prop_label IN VARCHAR2)

RETURN VARCHAR2;

FUNCTION get_member_prop_value

-- Return Member property value for current hierarchy for which -- logic script is being invoked

FUNCTION get_member_prop_value (p_prop_label IN VARCHAR2)

RETURN VARCHAR2;

FUNCTION get_parent_prop_value

-- Return Parent Member property value for current hierarchy for

which

-- logic script is being invoked

FUNCTION get_parent_prop_value (p_prop_label IN VARCHAR2)

RETURN VARCHAR2;

FUNCTION get_member_prop_value

-- Return Member property value for given Member

FUNCTION get_member_prop_value (p_member_id IN NUMBER

,p_prop_label IN VARCHAR2)

RETURN VARCHAR2;

FUNCTION is_numeric

-- This function will check if the given string is numeric or

not.

-- If numeric then return TRUE or else FALSE

FUNCTION is_numeric (p_string IN VARCHAR2)

RETURN BOOLEAN;

FUNCTION is_leaf

-- Check if current member is leaf or not

FUNCTION is_leaf

RETURN BOOLEAN;

FUNCTION get_descendants_count

-- This function provides count of direct descendants for a given

member id

FUNCTION get_descendants_count (p_member_id IN NUMBER)

RETURN NUMBER;

FUNCTION get_descendants_count (Overloaded)

-- This function provides count of direct descendants for a given

member name and application dimension id

FUNCTION get_descendants_count (p_app_dimension_id IN NUMBER

,p_member_name IN VARCHAR2

)

RETURN NUMBER;

PROCEDURE update_member_prop

/* This will add a line in request for Update Property of a

member

*/

PROCEDURE update_member_prop

(p_member_id IN NUMBER

,p_prop_label IN VARCHAR2

,p_prop_value IN VARCHAR2

,x_status OUT VARCHAR2

,x_message OUT VARCHAR2

)

;

FUNCTION get_req_attrib

FUNCTION get_req_attrib (p_request_id IN NUMBER

,p_what IN VARCHAR2

)

RETURN VARCHAR2

;

p_what Value

UDF1 (or UDF2 or UDF3) Returns value from UDF(1 to3) field of Request Header

REQUESTED_BY Returns User Name of the Requestor on the request

PRIORITY_CODE Provides code the Priority from the Request Header

WORKFLOW_NAME Provides name of the workflow from the request header

DESCRIPTION Provides description value from the request header

REQUEST_DATE Provides request date in the format DD-MON-RRRR

DUE_DATE Provides request due date in the format DD-MON-RRRR

FUNCTION get_req_attrib (Overloaded)

-- Provides request attribute for the current request

-- for which logic builder script is being executed

FUNCTION get_req_attrib (p_what IN VARCHAR2)

RETURN VARCHAR2

;

Email API Functions Package: EW_EMAIL_API These functions can be referred as ew_email_api.<Function Name>..

Send Email (no Template)

-- return Success / Failure code

-- success = 0 failure = 1

PROCEDURE send_email (p_recipients IN VARCHAR2

,p_subject IN VARCHAR2

,p_body IN VARCHAR2

,p_send_addr IN VARCHAR2 DEFAULT NULL

,p_ccs IN VARCHAR2 DEFAULT NULL

,p_bccs IN VARCHAR2 DEFAULT NULL

,x_result OUT NUMBER

)

Send Email (Email Template ID)

PROCEDURE send_email (p_request_id IN NUMBER

,p_email_template_id IN NUMBER

,p_email_vars IN g_email_vars

);

G_email_vars is a global variable in the Email API Package with type reference as mentioned below. This parameter can be used to specify Name/Value type of parameter that can be passed to the template. Email Template can refer to this variables and replace values in the template. If Request ID is passed then request id related information can be referenced in the template TYPE g_email_vars IS TABLE OF VARCHAR2(2000) INDEX BY VARCHAR2(50);

Send Email (Email Template Name)

PROCEDURE send_email (p_request_id IN NUMBER

,p_email_template_name IN VARCHAR2

,p_email_vars IN g_email_vars

);

Email Body Tables Using Request ID following tables can be inserted inside Email Body dynamically.

Email Table Description

<TABLE:VALIDATION_RESULT> Inserts Validation Results for a given request ID in the email Body

<TABLE:REQUEST_LINES> Inserts Request Line Details for a given request ID in the email body

<TABLE:ERP_REQUESTS> Inserts request IDs created during ERP Import in the email body. This table should be used in the email templates associated with the ERP Interface only.

<TABLE:DEPLOYMENT_RESULT> Inserts Deployment details for given request id in the email body.

For example in following email template, Deployment Result Table is referred in the email body. <TABLE:DEPLOYMENT_RESULT>

Request API Functions Package: EW_REQ_API These functions can be referred as ew_req_api.<Function Name>

Get Request Header Information

/* Get information from Request Header

Valid parameter values for p_what are

UDF1, UDF2, UDF3, REQUESTED_BY, PRIORITY_CODE

WORKFLOW_NAME, DESCRIPTION, REQUEST_DATE, DUE_DATE

*/

FUNCTION get_req_attrib (p_request_id IN NUMBER

,p_what IN VARCHAR2

)

RETURN VARCHAR2;

Insert note in the request

PROCEDURE ins_req_note

(p_user_id IN NUMBER

,p_request_id IN NUMBER

,p_notes IN VARCHAR2

);

Check if user can perform specific action on the given request Return Values are Y if action is allowed. Else N. X_msg -> Will return error message if any encountered.

FUNCTION chk_action_allowed



,p_app_dimension_id IN NUMBER

,p_action_code IN VARCHAR2

,p_hierarchy_id IN NUMBER

,p_new_member_name IN VARCHAR2

,p_moved_to_member_id IN NUMBER

,p_chk_line_exists IN VARCHAR2

,x_msg IN OUT VARCHAR2

)

RETURN VARCHAR2;

Parameters

Parameter Name Description

p_user_id User ID performing the action

p_request_id Request ID on which action check is being performed

p_app_dimension_id Application Dimension ID on which action check is being performed

p_action_code Action Code. See table for complete list of action codes . Please check with your target application to ensure which actions are valid or not.

p_hierarchy_id Hierarchy ID on which action is being taken upon

p_new_member_name New Member Name (pass NULL if the action is not creating new member)

p_moved_to_member_id Moved to Member ID (Pass NULL if the action is not move member)

p_chk_line_exists Pass Y or N to Check if the line already exists with the same action on the dimension

x_msg OUT parameter Returns error message if the function encountered any unexpected error

Check if the user need to perform any action on the given request id Return Y or N

FUNCTION chk_user_action_required

(p_request_id IN NUMBER

,p_user_id IN NUMBER

)

RETURN VARCHAR2;

Check if the user can perform specific action on the Dimension and in a request Return Y or N

FUNCTION chk_hier_action_allowed





)

RETURN VARCHAR2;

Parameters

Parameter Name Description

p_user_id User ID performing the action

p_request_id Request ID on which action check is being performed

p_app_dimension_id Application Dimension ID on which action check is being performed

p_action_code Action Code. See table for complete list of action codes . Please check with your target application to ensure which actions are valid or not.

Validate Insert Member Action

FUNCTION validate_insert_member

(p_source_app_dimension_id IN NUMBER

,p_source_member_name IN VARCHAR2

,p_target_app_dimension_id IN NUMBER

,p_target_parent_member_id IN NUMBER

,x_msg OUT VARCHAR2

)

RETURN VARCHAR2;

Check if the given hierarchy is in Create OR Edit mode in the request

/* Check if the given hierarchy id is in Create or Edit mode in

given request.

Return Request Line Id and flag to indicate Y/N if line

exists.

*/

PROCEDURE get_mem_prop_line_id



,p_hierarchy_id IN NUMBER

,x_request_line_id OUT NUMBER

,x_line_exists OUT VARCHAR2

);

Get Request Line Record

PROCEDURE get_req_line_rec (p_request_line_id IN NUMBER

,x_rec OUT ew_request_lines%ROWTYPE

);

Get Request Header Record

PROCEDURE get_req_rec


,x_rec OUT ew_request_headers%ROWTYPE

);

Get Request Status

FUNCTION get_req_status


)

RETURN VARCHAR2;

Valid Values returned would be

● Cancelled ● Completed ● New ● Submitted

Get Request Status Code

FUNCTION get_req_status_code


)

RETURN VARCHAR2;

Valid Values returned would be

● X (for Cancelled) ● C (for Completed) ● N (for New requests not submitted in the workflow) ● S (for requests Submitted in the workflow)

Get Request Header Workflow Status

FUNCTION get_req_hdr_wf_status


)

RETURN VARCHAR2;

Get Request Line Workflow Status

FUNCTION get_req_line_wf_status


,p_request_line_id IN NUMBER

)

RETURN VARCHAR2;

Get Current Workflow stage name for given Request ID

FUNCTION get_req_current_wf_stage


)

RETURN VARCHAR2;

Get Group Name on Request is pending action from Valid if the given request is in Review or Approve stage of the workflow.

/* Return Group Name of pending action from for a request

*/

FUNCTION get_pending_action_from


)

RETURN VARCHAR2;

Execute Request Header action

FUNCTION exec_hdr_action





)

RETURN VARCHAR2;

Execute Request Line Action

FUNCTION exec_line_action


,p_request_line_id IN NUMBER



)

RETURN VARCHAR2;

Get Request Lines Count

FUNCTION get_req_lines_count


,p_ignore_cancelled IN VARCHAR2 DEFAULT 'Y'

)

RETURN NUMBER;

Create Request Header Record

PROCEDURE create_request_header

(p_requested_by IN NUMBER

,p_request_date IN DATE

,p_due_date IN DATE

,p_description IN VARCHAR2

,p_udf1 IN VARCHAR2

,p_udf2 IN VARCHAR2

,p_udf3 IN VARCHAR2

,p_priority_code IN VARCHAR2

,p_wf_id IN NUMBER

,x_request_id OUT NUMBER


);

Create Request Line for Delete Member Action

FUNCTION create_line_delete_member






)

RETURN VARCHAR2;

Create Request Line for Remove Shared Member Action

FUNCTION create_line_remove_shared_mem




,p_parent_member_name IN VARCHAR2



)

RETURN VARCHAR2;

Create Request Line for Rename Member Action

FUNCTION create_line_rename_member







)

RETURN VARCHAR2;

Create Request Line for New Member Action

FUNCTION create_line_new_member






,p_prev_sibling_member_name IN VARCHAR2


)

RETURN VARCHAR2;

Create Request Line for Move Member Action

FUNCTION create_line_move_member





,p_moved_to_member_name IN VARCHAR2

,p_new_prev_sibling_member IN VARCHAR2 -- New Prev

Sibling


)

RETURN VARCHAR2;

Create Request Line for Reorder Children Action

FUNCTION create_line_reorder_children






,p_new_prev_sibling_member IN VARCHAR2


)

RETURN VARCHAR2;

Create Request Line for Edit Properties Action

FUNCTION create_line_edit_prop






,p_prop_label IN VARCHAR2

,p_prop_value IN VARCHAR2


)

RETURN VARCHAR2;

Create Request Line for Insert Shared Member Action

FUNCTION create_line_shared_member





,p_shared_member_name IN VARCHAR2

,p_prev_sibling_member IN VARCHAR2

,x_msg OUT VARCHAR2

)

RETURN VARCHAR2;

Send Reminder Email

PROCEDURE send_reminder_email



,p_email_to_user_id IN NUMBER

,p_notes IN VARCHAR2

,x_status OUT VARCHAR2


);

Hierarchy Acton code List BM Set as Base Member CM Create Member CMC Create Member As Child CMS Create Member As Sibling DM Delete Member ED Enable Descendants EM Exclude Member IMC Insert Member As Child IMS Insert Member As Sibling INCM Include Member ISMC Insert Shared Member As Child ISMS Insert Shared Member As Sibling P Edit Properties RC Reorder Children RM Rename Member RSM Remove Shared Member V View History X Cut ZC Paste As Child ZS Paste As Sibling

Security API Functions Package: EW_SEC_API These functions can be referred as ew_sec_api.<Function Name>. Following table provides common use functions for various Security Module related actions.

Purpose Function Name Input Parameters

Output Parameters

Get Group names separated by comma in which contains given user

get_user_groups User_id (if not passed then current logged in user id is used)

List of group names separated by comma in which consists user id.

Check if the user is in given group name or not

is_user_in_group Group Name (Required) User ID (if not passed then current logged in user id is used)

Y if the user is in Group else N

Check if the user is Active or Disabled

chk_user_active User Name (Required)

Y if the user is Active else N

Get Access Type for the Deployment module

get_dep_access_type User ID (if not passed then current logged in user id is used)

R or W or N R -> Read access W -> Write access N -> No access

Get Access Type for the Workflow module

get_wf_access_type User ID (if not passed then current logged in user id is used)

R or W or N R -> Read access W -> Write access N -> No access

Check if user has Read or Write access to Workflow module

chk_wf_access User ID (if not passed then current logged in user id is used)

Y if user has access N if user has no access

Check if user has Read or Write access to Deployment module

chk_dep_access User ID (if not passed then current logged in user id is used)


Check whether user has access to the App dimension or not.

chk_app_dim_access App_id App_dimension_id User ID (if not passed then current logged in user id is used) Access Type (Default is R) Valid Values : R or W


Check whether user has access to the Security Class or not

chk_sec_class_access

Security Class ID User ID (if not passed then current logged in user id is used) Access Type (Default is R) Valid Values: R or W


Check if user has given role or not

chk_user_role Role Type Code R -> Requestor V -> Reviewer A -> Approver D -> Default User ID (if not passed then current logged in user id is used)

Y if user has been assigned the role else N

User Management Security APIs Package: EW_SEC_API These functions can be referred as ew_sec_api.<Function Name>. These functions in the Security API package will help automate various functions to manage and maintain users/groups and their assignments within EPMWARE application. All of these functions will return “Success” if the task is completed successfully. If not then it will return “Error:<Error Message>”.

Purpose Function Name Input Parameters

Create new User create_user ● User Name

● First Name ● Last Name ● Email Address

● Native Flag (Y/N) (If N then Password is not required as its MSAD or LDAP user)

● Password ● Description

Enable User enable_user ● User Name

Disable User disable_user ● User Name

Create New Group create_group ● Group Name

Enable Group enable_group ● Group Name

Disable Group disable_group ● Group Name

Assign user to Group assign_user_to_group ● User Name

● Group Name

Unassign user to Group unassign_user_to_group ● User Name

● Group Name

Agent API Functions Package: EW_AGENT_API Purpose of this package is to invoke custom agent scripts from Logic Builder. Custom tasks in workflow can leverage this API to execute certain commands on the remote server using EPMWARE agent. These functions can be referred as ew_agent_api.exec_agent_cmd Before calling this function there are prerequisites to be satisfied as mentioned below.

1. On the target server add name (with full path) of the script to be executed by this remote agent in the file “ew_custom_agent_scripts.lst”. This file is located in the home directory of the EPMWARE target Agent.

2. Commands passed to this Agent API entered in this file will be matched and if exists then only it will be executed. This will prevent calling any unauthorized script from Agent API.

For example, as shown below, “ew_test.sh” is the remote script could be executed by Agent API.

.

exec_agent_cmd (p_app_name IN VARCHAR2 ,p_agent_cmd IN VARCHAR2 ,p_agent_type IN VARCHAR2 DEFAULT 'D' -- Reserved ,p_send_files IN VARCHAR2 DEFAULT 'N' ,p_output_file_name IN VARCHAR2 DEFAULT NULL ,p_output_file_loc IN VARCHAR2 DEFAULT NULL ,p_dep_file_loc IN VARCHAR2 DEFAULT 'stage' ,p_agent_cmd_type IN VARCHAR2 DEFAULT NULL ,p_timeout_minutes IN NUMBER DEFAULT 15 ,p_param_name_1 IN VARCHAR2 DEFAULT NULL ,p_param_value_1 IN VARCHAR2 DEFAULT NULL ,p_param_name_2 IN VARCHAR2 DEFAULT NULL ,p_param_value_2 IN VARCHAR2 DEFAULT NULL ,p_param_name_3 IN VARCHAR2 DEFAULT NULL ,p_param_value_3 IN VARCHAR2 DEFAULT NULL ,p_param_name_4 IN VARCHAR2 DEFAULT NULL ,p_param_value_4 IN VARCHAR2 DEFAULT NULL ,p_param_name_5 IN VARCHAR2 DEFAULT NULL ,p_param_value_5 IN VARCHAR2 DEFAULT NULL ,p_param_name_6 IN VARCHAR2 DEFAULT NULL ,p_param_value_6 IN VARCHAR2 DEFAULT NULL ,p_param_name_7 IN VARCHAR2 DEFAULT NULL ,p_param_value_7 IN VARCHAR2 DEFAULT NULL ,p_param_name_8 IN VARCHAR2 DEFAULT NULL ,p_param_value_8 IN VARCHAR2 DEFAULT NULL ,p_param_name_9 IN VARCHAR2 DEFAULT NULL ,p_param_value_9 IN VARCHAR2 DEFAULT NULL ,p_param_name_10 IN VARCHAR2 DEFAULT NULL ,p_param_value_10 IN VARCHAR2 DEFAULT NULL ,x_status OUT VARCHAR2 ,x_message OUT VARCHAR2

);

API Parameters

Parameter Name Expected Value Required OR Optional

p_app_name Application Name Required

p_agent_cmd Remote Script name with full path. Note: This should match with the entry in the file “ew_custom_agent_scripts.lst” on the remote (Target) server.

Required.

p_agent_type D (Reserved for future use) Optional

p_send_files N (Reserved for future use) Optional

p_output_file_name Name of the output file generated by the custom script. Note: If value is not provided then default name will be generated based on TASK_ID and assigned.

Optional.

p_output_file_loc Location of the output file generated by the custom script . Note: If the value is not provided then default location under “stage” folder will be used.

Optional

p_dep_file_loc Stage (Reserved for future use) Optional

p_agent_cmd_type Agent Command Type (Reserved for future use) Optional

p_timeout_minutes Maximum Time (in Minutes) allocated for Remote Agent script to complete its task. Default value is 15 minutes

Optional

p_param_name_<nn> Parameter Name. Note: Agent API Script will pass values for optional parameters. Parameter names are stored for audit purposes in EPMWARE. Only Values are passed.

Optional

p_param_value_<nn> Parameter Value. Note: Agent API Script will pass values for optional parameters. Parameter names are stored for audit purposes in EPMWARE. Only Values are passed.

Optional

x_status RETURN Status code. S for success and E for Error

x_message RETURN Error Message

Remote Custom Script requirements Remote script will be passed following parameters

1. Fixed Parameters 1.1. Task ID (There will be a folder created under stage folder on the remote server

automatically with this task id as folder name. This folder can be used to generate log or out files by the custom script if needed).

1.2. Application Type 1.3. Action (Fixed value passed: CUSTOM) 1.4. Application Name 1.5. Application Version 1.6. Application User Name 1.7. Application Password

2. Script Parameters 2.1. Parameter values (1 to 10) passed to the Agent API

Examples

Pre/Post Deployment Tasks Following example shows one logic builder script that is used for both Pre and Post

Deployment tasks. This script will simply send email notifications to users. This example shows how to create deployment tasks and other configurations necessary before it is used.

Prerequisites for this example

● Create Email Template ● Create Logic Builder Script ● Create Deployment

Create Email Template

Navigate to Configuration -> Email menu and open Email Templates page.

Create new Email Template for this example as shown below. This Email Template will be used in the custom Deployment Tasks.

Create Logic Builder Script

Navigate to Logic Builder -> Scripts page and create new Script Type as shown below for this example.

Logic Script

Use following code for the example.

DECLARE l_email_vars ew_email_api.g_email_vars; l_email_template VARCHAR2(100); BEGIN ew_lb_api.g_status := ew_lb_api.g_success; ew_lb_api.g_message := NULL; /***** If the deployment configuration is TBC then send email ******/ IF ew_lb_api.g_dep_config_name = 'TBC' THEN l_email_template := 'TBC Deployments'; l_email_vars('DEPLOYMENT_ID') := ew_lb_api.g_deployment_id; l_email_vars('DEPLOYMENT_STAGE') := ew_lb_api.g_dep_stage; l_email_vars('DEPLOYMENT_STATUS') := ew_lb_api.g_dep_status; IF ew_lb_api.g_dep_stage = 'PRE' THEN l_email_vars('DEPLOYMENT_NOTES') := 'Deployment is about to start.';

ELSE -- POST deployment l_email_vars('DEPLOYMENT_NOTES') := 'Check deployment data in the target app..'; END IF; ew_email_api.send_email (p_request_id => ew_lb_api.g_request_id ,p_email_template_name => l_email_template ,p_email_vars => l_email_vars ); END IF; EXCEPTION WHEN OTHERS THEN ew_lb_api.g_status := ew_lb_api.g_error; -- Error ew_lb_api.g_message := TBC Email Template Error : '||SQLERRM; END;

Create Deployment

Navigate to Deployment -> Manager tab and create new deployment as shown below.

Assign application to the Deployment. Click on the Application hyperlink and open Applications popup to assign application to

this deployment.

Assign Schedule to this deployment

How to test

Create request and submit in the workflow to check its deployment triggers these tasks. Ensure that workflow has deploy task and deployment configuration is applied to the application in the request.

l o g i c b u i l d e r g u i d e - epmware.com logic builder guide.pdf · l o g i c bu i l d e r g...

Documents