Apex Integration Guide

Apex is a new predictive and generative AI-based Enterprise Service Management (ESM) platform to turbocharge productivity, simplify work, and create delightful experiences for end users, IT teams, and executives.
Apex delivers responsive, effective, and efficient ESM capabilities with a lightweight architecture to roll out new services and resolve service requests up to 50% faster using generative AI.  

Curious to learn more about Apex, refer to Apex Documentation Site.

The latest Service Automation V7SP4 enables integration with Apex which involves a few configuration procedures. Let's dig in and understand in detail.

Figure: Integration with Apex

I. Install Service Automation V7SP4 to integrate with Apex

To integrate Service Automation V7SP4 and Apex, perform the following steps:

1.  In IIS, create an application/virtual directory for UI. Name it OrchestrationUI. 
2.  In IIS, create an application/virtual directory for API. Name it Summit.API.Orchestration.
   
3.  Update DB connection string in API.
4.  Update Apex users' details to Service Automation users' table.
5.  Update Product name from SUMMIT to SUMMITNTP
    i. In table ORC_ITSMSettings  
   II. Service Automation API Config
   <add key="App:ProductName" value="SUMMITNTP"/>
6.  Access Service Automation UI URL and log in to the portal.
7.  Install and configure Event Listener Service and Execution Service. 

II. Service Automation navigation and configuration on Apex 

Service Automation configuration on Apex requires Application, Service Portal, and a Widget. Perform required changes in Service Portal and Widget.

To configure Service Portal and Widget to integrate Service Automation with Apex, perform the following steps:

1.  Log in to Apex and select the Role as Designer. Click Proceed.
   Figure: Role selection
   
   
2.  Click Settings icon and select Design Studio as shown below.
   Figure: Settings - Design Studio
    
3.  Select Service Automation Application. Navigate to Application > Service Portal.
   Select the desired Domain and Sub Domain. The Service Portal List page is displayed.
   Figure: Application - Service Portal
   
   
4.  Click the configured Service PortalID hyperlink to configure or make changes. The configuration must be changed to Maintenance state to edit or make changes. That can be done by navigating to Publish step and changing the state from Published to Maintenance.
   Click Update.
   Figure: Publish stepper
    
5.  Click the same ID which is now in Maintenance state to perform the configuration. In the General tab, update all the field details as per requirements and click Next.
   Figure: General tab
   
   
6.  In the Design Portal, select the Service Automation Widget and access the Settings.
   Execute the following changes in Code >Javascript.

async function getUrlToRedirect(bodyCSSVariables) {
        const res = await fetch("https://localhost/api.orchestration/api/auth/createssopackage", {
            method: "POST",     
            body: JSON.stringify({
                "UserId": userSession.id,
                "bodyCSSVariables" :bodyCSSVariables
            }),
            headers: {
                'Content-Type': 'application/json;  charset=UTF-8',
                'Access-Control-Allow-Origin': 'https://integrations.apex.com,'
                }
            });
        return res.json();
    };

Update the API URL link in fetch function. Specify the Apex application base URL under the Access Control Allow Origin function.

7.  Save and Publish the Service Portal. Click the Widget and navigate to Service Automation application.

III. Configurations in Service Automation application

ITSM requires an update to the Apex API Base URL. Additionally, the Data Source should be configured to retrieve Domain, Tenant, and Users, with a corresponding update to the field mapping for these elements under Field Mapping.

1.  Navigate to Menu > Integrations > Manage Integrations > ITSM.
2.  On the ITSM Configurations page, specify the API base URL in Base URL field and validate.
   Figure: ITSM Configurations page
3.  Navigate to Menu > Integrations > Manage Integrations > Data Sources.
4.  Specify Apex API URL, Method Type, Headers, and Payload to fetch Domain, Tenant, and Caller.
   Figure: Data Sources
5.  Navigate to Menu > Integrations > Manage Integrations > Field Mapping.
6.  In the General module, update the data source name and the fields for domain and perform the Response Mapping as shown below.
   
7.  Update Proxy IP Mapping.

IV. Trigger a Workflow from Apex Service Management

To initiate a Workflow upon the creation or update of an Incident/Request, the following steps should be performed on Apex.

Prerequisites:

• Set up an API Trigger Workflow in Service Automation to retrieve and download request details
• Obtain the SA token

1.  To trigger the workflow for service requests log in to Apex as an Application Designer.

To configure an API by using API Trigger URL and its payload, perform the following steps:

1.  Navigate to Settings > Design Studio.
2.  Select Service Management Application.
3.  In the Module drop-down, select Service Request.
4.  Navigate to Designers > API Configuration.
5.  Update all the required data. Mention the Service Automation URL to trigger a specific workflow.
6.  Use API Trigger Workflows request details to configure the API.

Figure: API Configuration page

Figure: API Configurations Details page

To configure a business rule, perform the following steps:

1. Navigate to Settings > Design Studio.
2.  Select Service Management Application.
3.  In the Module drop-down, select Service Request.
4.  Navigate to Designers > Business Rule Designer.
5.  Select the desired Domain and Sub Domain from the drop-down. Click New to configure a new business rule.
6.  In the General tab, under the Table field, select the Service Catalog name for which automation has to be configured.
   Figure: Business Rule Designer - General tab
   
   
7.  Specify all the required conditions in the General, Trigger, and Condition tab.
8.  In the Actions tab, click ADD API. 
9.  In the Add API pop-up, update the information as shown below.
   Figure: Add API

V. View Workflow details on Apex Request/Incident details page

Prerequisites:

• Create a new tab named "Automation" for the Request/Incident details form
• Make a note of the Automation tab ID

To view the workflow details, perform the following steps:

1.  Log in to Apex as an Analyst and navigate to Service Request > Manage Service Request.
2.  In the Manage Service Request List page, click the desired SR ID by using Open link in new window option.
   Figure: Manage Service Request List page
   
   
3. In the newly opened SR details page, click Custom Script from the top panel and select Page Custom Script.
   Figure: Manage Service Request Details page
   
   
4.  In the Custom script window, Select Typescript. In the Typescript window, add /update the below script and update the Automation Tab ID and save the configuration.

$("#tab_orchestration_ZGHW7414").parent().on("click",function(){

setTimeout(function () {

__this.bindClientScript();

}, 1000);

});

In Client Script update  SA API base URL in variable orchestrationAPIBaseURL and SA UI base URL in variable orchestrationUIURL. Update SA token in _token variable.
Figure: Automation tab

5.  Log a Service Request for the configured catalog and navigate to Manage Service Request and open an SR which has Workflow details. Workflow details are displayed under the Automation tab.

Summary of URL Updates 

The following segment provides a summary of all URL updates:

• Update Service Automation UI base URL in the following:

1.  SA API Application Settings Config file.
   <add key="ServiceAutomationSSOUrl" value="http://localhost:4200/orchestrationui/#/authtransitionhandler?token={0}"/> 
   
   
2. Apex, Custom Script Page custom script of IM Manage Incident or SR Manage Service Request a Client Script 

var orchestrationUIURL='https://ntpautomation.symphonysummit.com/orchestrationui'; 

• Update Service Automation API base URL in  the following:

1. SA Angular fileorchestrationui\assets\config\app-config.json {
       "API_Base_Url": "http://localhost/summit.api.orchestration"
   }
   
   
2. Apex, Custom Script Page custom script of IM Manage Incident or SR Manage Service Request a Client Script 

   var orchestrationAPIBaseURL='https://ntpautomation.symphonysummit.com/summit.api.orchestration';
   
   

3. Apex, Service Portal à Service Automation Widget Settings Code Javascript.

   Update the SA API base URL in fetch method.