How to configure new custom actions on the action bar in “Planning” / “Details” Page?
Custom actions on the “Planning” and “Details” page can be configured using action bar. Any custom action that is configured will appear with in the action bar (More Actions) of the page.
Planning page:
Details page:
For both the pages (Planning and Details), OOB those are the actions that are provided as per the screenshot.
How can we do this for Planning or for Details Page?
If you would like to add custom actions on the action bar, you can follow the below steps: (We will be using the platform Now experience framework for defining actions. If you want to know more about the Declarative actions in service now, Please refer Declarative Actions in ServiceNow: The COMPLETE Guide)
Note: Below are the steps for the Servicenow instances which have project workspace
application installed on top of Vancouver release. For the instances on Washington or Washington+, these steps may vary.However, overall concept of configuring the actions is same.
Assume we would like to add a custom action called “My Custom Action” to the planning/details page.
Step – 1: First create an action bar declarative action.
- Click on “New” button.
- You can fill any name as action label. Ex: My Custom Action
- You can fill action name w.r.t to the action label given. Ex: my_custom_action
- It has to be implemented as “UXF Client Action”
- You can create a new “Action Payload Definition” for each different custom action.
- Label can be any name. Ex: My Custom Action
- Key can be given w.r.t to the label. Ex: my_custom_action
- Select Applicable to as “form”
- You can give payload if it is required. It’s not mandatory to be filled.
- Select the newly created “Action Payload Definition” as client action
- Select Table as “pm_project”. Because this newly created declarative action should work against only “pm_project” entity.
- Save
This step is common irrespective of whether the intention is to create action in planning or action in details page.
Step – 2: Create UX Form Action using the above created declarative action.
Details:
- Click on “New” button
- You can fill name as any name. Ex: My Custom Action
- Select Action type as “Declarative Action”.
- Select the table as “pm_project”. Because this is the form action that we are going to create against the pm_project entity.
- Select the action “My Custom Action” that we have created in step – 1 as declarative action.
- Save
This step is common irrespective of whether the intention is to create action in planning or action in details page.
Step – 3: Add the declarative action we created in step - 1 to the UX Action Configuration which is responsible for displaying new action in action bar of planning/details page in project workspace.
Details for planning page:
- We must add the newly created declarative action to the UX Action Configuration that is configured OOB for the planning page. Hence, we will add it to the “Project Workspace action config)
- Open Action bar declarative actions -> My Custom Action
- Find the related list “Action Configurations” and click on edit
- Select “Project Workspace action Config” (Which exists OOB) in the list.
Details for details page:
- We must add the newly created declarative action to the UX Action Configuration that is configured OOB for the planning page. Hence, we will add it to the “Project WS Record Page Action Config”)
- Open Action bar declarative actions -> My Custom Action
- Find the related list “Action Configurations” and click on edit
- Select “Project WS Record Page Action Config” (Which exists OOB) in the list.
Step – 4: Add the UX Form action we created in the step – 2 to the UX Form Action Layout under the action config.
Details for planning page:
- We also need to add this new UX Form Action to the UX Form Action Layout that is configured OOB for the planning page. Hence, we are adding this form action to the Planning page action layout.
- Open the Project Workspace action config
- Find the related list “UX Form Actions Layout” and Select “Planning Page action layout”
- Find the related list “UX Form Action Layout item” and click on “New”
- Select the table as “pm_project” as it should be applicable only for the pm_project entity
- You can fill label as any label: Ex: My Cusotm Action
- You can fill name as any name w.r.t label. Ex: my_custom_action
- You can enable “Overflow”, if you think action has to come in the overflow menu else it will appear as individual button next to the overflow menu on Planning page.
- Item type has to be “Action”
- Select the UX form action that we created in step – 2 as an Action
- If required you can give the number in order
- Save
Details for Details page:
- We also need to add this new UX Form Action to the UX Form Action Layout that is configured OOB for the planning page. Hence, we are adding this form action to the Record page action layout.
- Open the Project WS Record Page Action Config
- Find the related list “UX Form Actions Layout” and Select “Record Page action layout”
- Find the related list “UX Form Action Layout item” and click on “New”
- Select the table as “pm_project” as it should be applicable only for the pm_project entity
- You can fill label as any label: Ex: My Cusotm Action
- You can fill name as any name w.r.t label. Ex: my_custom_action
- You can enable “Overflow”, if you think action has to come in the overflow menu else it will appear as individual button next to the overflow menu on Planning page.
- Item type has to be “Action”
- Select the UX form action that we created in step – 2 as an Action
- If required, you can give the number in order
- Save
Step -5: Now, we can see that custom action appeared in the planning/details page of project workspace. (Note: So far, we haven’t added the behavior to the custom action).
Step -6: To add the behavior to our custom action, we must configure “UX Add on event mapping” for the declarative action we created in Step – 1.
Details for planning page:
- We need to create add on event mapping to the declarative action that we have created on step – 2 to provide click behavior to the action in planning page.
- Open UX Form Action – My Custom Action – Open Declarative action (my_custom_action)
- Find the related list “UX Add on Event Mappings” and click on New
- Fill any name as Event Mapping Name. Ex: Event Mapping for Custom Action on Plng Page
- Source Element Id must be always “action_bar_1”. Because this is the id name of action bar component that we are using in Planning page.
- Select the parent macroponent as “Planning”. Because we would like add the behavior to the “My Custom Action” that appears on “Planning” page. Hence parent macroponent should be planning.
- Select the target event always as “PWS Common Action Handler”. This event was created OOB as a customization hook. So, whenever “My Custom Action” on the planning is clicked, it triggers the OOB ux client script (PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ACTION_BAR_ON_CLICK) that is configured under “PWS Common Action Handler”. This way we are making sure that implementors should not change the OOB macroponent as it impacts the upgrade.
- We must fill the target payload mapping. Because for every custom action that you are going to add in the planning page, you will tie the same target event that has mentioned in step 1.7. Hence the same ux client script (PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ACTION_BAR_ON_CLICK) gets triggered for all your different custom actions. Whatever payload that we give in “target payload mapping” can be used as differentiation factor while writing the code for each customized action.
- Save.
Details for Details page:
- We need to create add on event mapping to the declarative action that we have created on step – 2 to provide click behavior to the action in details page.
- Open UX Form Action – My Custom Action – Open Declarative action (my_custom_action)
- Find the related list “UX Add on Event Mappings” and click on New
- Fill any name as Event Mapping Name. Ex: Event Mapping for Custom Action on Details Page
- Source Element Id must be always “ui_action_bar”. Because this is the id name of action bar component that we are using in Details page.
- Select the parent macroponent as “record Default”. Because we would like add the behavior to the “My Custom Action” that appears on “Details” page. Hence parent macroponent should be “record Default”.
- Select the target event always as “PWS Common Action Handler”. This event was created OOB as a customization hook. So, whenever “My Custom Action” on the planning is clicked, it triggers the OOB ux client script (PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ACTION_BAR_ON_CLICK) that is configured under “PWS Common Action Handler”. This way we are making sure that implementors should not change the OOB macroponent as it impacts the upgrade.
- We must fill the target payload mapping. Because for every custom action that you are going to add in the details page, you will tie the same target event that has mentioned in step 1.7. Hence the same ux client script (PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ACTION_BAR_ON_CLICK) gets triggered for all your different custom actions. Whatever payload that we give in “target payload mapping” can be used as differentiation factor while writing the code for each customized action.
- Save.
Step – 7: Updating the code in script handler to customize the behavior on click of custom action.
Details for planning page:
- Open sys_ux_client_script.LIST and find the script with name PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ACTION_BAR_ON_CLICK
- Add your custom code handling here. While creating add on event mapping, based on the action_type we have given in target payload mapping we can add custom code either by using switch cases or if else conditions. Example can be seen in below video.
- Save.
Details for Details page:
- Open sys_ux_client_script.LIST and find the script with name PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ACTION_BAR_ON_CLICK
- Add your custom code handling here. While creating add on event mapping, based on the action_type we have given in target payload mapping we can add custom code either by using switch cases or if else conditions.
- Save.
So far, we have created UX Form action and added it to the planning page / details page action bar and added on click behaviour to it.
How can we customize if custom action click involves showing a modal?
If the requirement is to show a modal with ok and cancel buttons on click of custom action, please follow the below steps:
Step – 1: In “Planning”/ “Details” page of project workspace, add subpage in the “viewport_1” resides in Custom Modal Viewport.
Details for planning page:
- Whatever subpage we are creating under this viewport will be displayed in the modal. Hence the UI contents that we are placing in the subpage should be similar to the general modal user experience.
- Open UI Builder -> Project Workspace
- Select Planner > Planner Default
- In the left-hand side panel, Select an element with viewport name “Viewport 1” with id “viewport_uld”
- In the right-hand side panel, select “Edit Content” under “config” tab.
- Select Planning > Planning Default
- In the left hand side panel, under modals and popover, find an element with name “Custom Modal Viewport”( modal_viewport_1) – Select “viewport 1” (viewport_1)
- In the right-hand side panel, select “Edit Content” under “config” tab.
- Create page under this viewport. (It will be a subpage and parent of this subpage will be the planning page)
- While creation make sure the route/url-path that is given. Example: my-custom-action-modal-page
Details for Details page:
- Whatever subpage we are creating under this viewport will be displayed in the modal. Hence the UI contents that we are placing in the subpage should be similar to the general modal user experience.
- Open UI Builder -> Project Workspace
- Select Planner > Planner Default
- In the left-hand side panel, Select an element with viewport name “Viewport 1” with id “viewport_uld”
- In the right-hand side panel, select “Edit Content” under “config” tab.
- Select Details > details Default
- In the left hand side panel, under modals and popover, find an element with name “Custom Modal Viewport”( custom_modal_viewport) – Select “viewport 1” (viewport_1)
- In the right-hand side panel, select “Edit Content” under “config” tab.
- Create page under this viewport. (It will be a subpage and parent of this subpage will be the details page)
While creation make sure the route/url-path that is given. Example: my-custom-action-modal-page
Step – 2: Setting up the contents in the subpage (page which will contain the contents of modal that we are going to display) that we created. (Example for reference)
Details:
- Add a simple header and OK, CANCEL buttons.
This step is common irrespective of whether you are handling action in planning or action in details page.
Step – 3: Opening the newly created subpage (page which will contain the contents of modal that we are going to display) on viewport modal on click of custom UI action.
Details for planning page:
- We can use the same OOB UX Client Script (PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ACTION_BAR_ON_CLICK) to customize the behavior of opening a viewport modal with subpage that we have created in step -1.
- Open a UX client script (PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ACTION_BAR_ON_CLICK) and add the code to open the modal. We must give same route name or url path name of newly created subpage. Example can be seen in video.
Details for details page:
- We can use the same OOB UX Client Script (PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ACTION_BAR_ON_CLICK) to customize the behavior of opening a viewport modal with subpage that we have created in step -1.
- Open a UX client script (PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ACTION_BAR_ON_CLICK) and add the code to open the modal. We must give same route name or url path name of newly created subpage. Example is similar to the way we are doing for planning page.
Step – 4: As our custom modal has OK and Cancel buttons, now we need to bind these button click events to the OOB event in “Planning” / “Details” page.
Details for planning page:
- Basically, on click of OK or CANCEL Button – We need to emit an event using api.emit API in the script handlers of OK or CANCEL button on click events (Example: “BTN_CLICKED_IN MY_CUSTOM_ACTION_MODAL_PAGE”).
- Now, we have to declare this event under the dispatched events on newly created subpage. (page that you created in step -1)
- Add an event handler called “Button clicked in planning viewport” which is an inherited event handler. “Button clicked in planning viewport” is the OOB event that we have provided in “Planning” page. Reason behind tying this inherited event to the event that we are dispatching on OK/CANCEL button click handlers is that it triggers the OOB UX Client script “PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ON_VIEWPORT_MODAL_ACTION” on button clicks.
- While adding the event handler, you have to map the expected payload with the payload that you are passing while emitting event. Your payload format in the script api.emit should be in accordance with the expected payload format. Example can be seen in below video
Details for Details page:
- Basically, on click of OK or CANCEL Button – We need to emit an event using api.emit API in the script handlers of OK or CANCEL button on click events (Example: “BTN_CLICKED_IN MY_CUSTOM_ACTION_MODAL_PAGE”).
- Now, we have to declare this event under the dispatched events on newly created subpage. (page that you created in step -1)
- Add an event handler called “Button clicked in viewport” which is an inherited event handler. “Button clicked in viewport” is the OOB event that we have provided in “Details” page. Reason behind tying this inherited event to the event that we are dispatching on OK/CANCEL button click handlers is that it triggers the OOB UX Client script “PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ON_VIEWPORT_MODAL_ACTION” on button clicks.
- While adding the event handler, you have to map the expected payload with the payload that you are passing while emitting event. Your payload format in the script api.emit should be in accordance with the expected payload format. Example is similar to the way we are doing for planning page.
Step -5: As we have binded OK and CANCEL button events on the modal page to the Planning/Details page, now we have to customize the script that gets triggered on execution of OK and CANCEL button clicks.
Details for Planning page:
- Now, it’s time to add customized logic on click of “OK/CANCEL” button on the modal.
- As we have discussed in step – 4 under 1.3, We have to add code in the UX Client script. Open sys_ux_client_script with name “PWS_CUSTOM_SCRIPT_HANDLER_PLANNING_ON_VIEWPORT_MODAL_ACTION”
- Add your custom code that you would like to process on click of OK or Cancel Buttons. Example can be seen in video
- Save.
Details for Details page:
- Now, it’s time to add customized logic on click of “OK/CANCEL” button on the modal.
- As we have discussed in step – 4 under 1.3, We have to add code in the UX Client script. Open sys_ux_client_script with name “PWS_CUSTOM_SCRIPT_HANDLER_DETAILS_ON_VIEWPORT_MODAL_ACTION”
- Add your custom code that you would like to process on click of OK or Cancel Buttons. Example is similar to the way we are doing for planning page.
- Save.
That’s it. We have now successfully done with
1) Adding custom action on the planning/details page
2) Opening a modal on click of custom action
3) Handling the actions taken on the modal.
Note: If on click of “OK/CANCEL” buttons is not working as expected for planning page, Please find OOB UX Client script with name “Button clicked in planning viewport modal” and make we sure we are emitting the event “CUSTOM_HANDLER_ON_PLNG_VIEWPORT_MODAL_SUCCESS” in else condition. If it’s not the mentioned event, please update in the script. This is a known bug. Also, don’t forget to enable the replace_on_upgrade flag to true for the modified script.
If you are planning to migrate the UI actions from classic form to next experience details page - Please refer this article
