Notifications

426 views

Description

The Slack spoke is an available integration through IntegrationHub

Cause

The next steps are just a reference that could be useful to test your Slack WebSpoke Integration

Resolution

1. Request Plugin Activation through the HI Service Portal

The ServiceNow Integration Hub Installer plugin (com.glide.hub.integrations) requires a separate subscription and must be activated by ServiceNow personnel, so it will not appear in the System Definition > Plugins list in your instance.

To purchase a subscription, contact your ServiceNow account manager. The account manager can arrange to have the plugin activated on your organization's production and sub-production instances, generally within a few days.

If you do not have an account manager, decide to delay activation after purchase, or want to evaluate the product on a sub-production instance without charge, you will need to make a separate request in the HI Service Portal to have it activated. Follow these steps:

  •  Click the Request Plugin button from the plugins page. HI will open in another browser tab

  •  In HI, navigate to Service Catalog and click on the Activate Plugin link.

  • Fill out the form:
    • Target instance: Instance on which to activate the plugin
    • Plugin Name: Name of the plugin to activate
    • Reason/Comments: Any information that might be helpful
    • Select Maintenance Start Time: Select a time from one of the available time slots*
      *Note: Date and time must be at least 2 business days from the current time.
  • Click on Submit.

2. Be aware of relevant roles

Relevant Roles When IntegrationHub is installed, one new role is created - integration_hub_admin. In addition, several existing roles play important parts in the newly extended system. Below is a breakdown of the capabilities for each of these roles:

  • IntegrationHub Admin (integration_hub_admin): This role grants access to: Connections, Credentials, Web Services, SOAP Security Policies, MID Server Script Files, Action Designer and Flow Designer


  • Flow Designer (flow_designer): This role enables users to launch Flow Designer


  • Flow Operator (flow_operator): This role allows access to Flow Designer operations information


  • API Analytics Read (api_analytics_read): This role allows users to read API Analytics data


  • Admin (admin): Admin has full access to IntegrationHub and Flow Designer

3. Explore the method you would like to call


For example, the getQuestion method is a public API that requires no authentication. It selects a random ServiceNow Trivia question and returns a JSON response that includes four fields:

  • difficulty
  • question
  • category
  • sys_id

A sample response from the API is shown below:

<response>
<result>
<difficulty>Medium</difficulty>
<sys_id>2b6r2ef8db4fe34078fa594e5e96198f</sys_id>
<question>
If you are updating records on another table in a business rule,
what value should you use for the “when” field?
</question>
<category>Business Logic</category>
</result>
</response>

Sample response from getQuestion method.

Create Client Spoke

A Spoke is a scoped application that contains a set of IntegrationHub actions published for re-use by Flow Designer users. Per best practice, include the word 'spoke' as part of the application scope name.

(1) System Applications > My Company Applications.

(2) Select the Create new button.

(3)Next to Start from scratch, select Create.

(4) Complete the record as shown.

  • Name: SN Trivia Spoke
  • Scope: x_<12345>_sn_trivia

'12345' will be replaced by the company code assigned to your instance.

(5) Select OK. 

(6) Confirm application creation by selecting OK.

(7) Select Edit Application to open Studio in a new browser tab.

The scope for Flow Designer Flows or Custom Actions is set explicitly when creating new Flow Designer Flows and Actions. 

The scope selected in the Application picker does not dictate scope as it does in other application development efforts.

(8) Optional - Set an Icon for the Spoke : From within Studio, select File > Settings.

(9) Optional -   In a separate browser tab, find and download an icon image suitable for a Trivia application or use one of the images below. The dimensions should be approximately 45 pixels x 45 pixels.

In a separate browser tab, find and download an icon image suitable for a Trivia application or use one of the images below. The dimensions should be approximately 45 pixels x 45 pixels.

(10) Within Application Settings, in the Logo field, select Click to add... and upload your icon image.

4. Create the 'Get Trivia Question' Action

Actions are developed by technical users to encapsulate complex operations and expose user-friendly code-less configuration options to Flow Designer users. 

(1) Open the Flow Designer interface and create a new Action using one of the following methods:

  • Option 1: Access Flow Designer from Studio
          Select Create Application File.
          Select Flow Designer > Action.
          Create.
             Note: Flow Designer opens in a new browser window.


  • Option 2: Access Flow Designer from the main ServiceNow window
          Flow Designer > Designer.
          From within the Flow Designer interface, select New > New Action.
             Note: Flow Designer opens in a new browser tab.

(2) Configure the Action Properties. 

  • Name: Get Trivia Question
  • Accessible From: All Application Scopes
  • Description: Get a random ServiceNow Trivia Question.
  • Application: SN Trivia Spoke
  • In-Flow Annotation: Get a random ServiceNow Trivia Question.

(3) Submit.

(4) Define the Inputs and Outputs of the Action.

Inputs

  • No inputs are required for this action.

Outputs

  • Select Outputs in the Action Outline and define four outputs.
  • Populate the Labels only. Values will be associated with the outputs later in the lab.)
    • Difficulty
    • Question
    • Category
    • Question ID

(5) Select the plus (+) symbol in the Action Outline to insert a new step.

(6) Add a REST step to call the getQuestion API method. 

(7) Configure the REST step.

  • Name: Call getQuestion Method
  • Connection: Define Connection Inline
  • Base URL: http://BASE_URL
  • Resource Path: /api/x_snc_now_trivia/trivia/getQuestion
  • HTTP Method: GET
  • Headers:
    • Name: Content-Type
    • Value: application/json
    • Name: Accept
    • Value: application/json

(8) Save


The next part introduces Connections and Credentials, which should be used as a best practice. However, some advanced use cases may require inline connections.

5. Create a Flow to Test the Action

(1) Select the home tab in Flow Designer.

(2) Select New > New Flow.

(3)Set the Flow Properties.

  • Name: Test Trivia Spoke
  • Application: SN Trivia Spoke
  • Run As: User who initiates session

(4) Submit.

(5) From the More Actions menu (icon with 3 vertical dots),  select Configurations > Show draft actions.

Show draft Actions in Flow Designer to allow for testing before Actions are published.

(6) Define a Trigger for the flow.

  • Within the Trigger section, select Click to add a Trigger.
  • Set Trigger properties.
    • Trigger: Run Once
    • Run on: (choose any date in the future)
  • Done

(7) Add an Action.

  • Within the Actions section, select Click to add an Action, Flow Logic, or Subflow.
  • Select Action.
  • In the SN Trivia spoke, select Get Trivia Question.
  • Done.

(8) Save the Flow.

(9) Test the Flow.

  • Test > Run Test.
  • Click Flow has been executed. To view the flow, click here.

(10) Inspect the Execution Details.

  • Select the Get Trivia Question Action to expand it.
  • Select Steps to expand the Action steps.
  • Within Step 1 - Call getQuestion Method [REST], review the Step Output Data runtime values to validate the following:
    • Response Body - <Should show well-formed JSON code containing a trivia question>.
    • Status Code - 200

Step output validation for REST step showing a Status Code of 200 and a Response Body that includes well-formed JSON with a trivia question included.

If the execution details do not show a successful call to the REST API, review the steps to troubleshoot.

6. Add a Step to Parse the Response Body

Now that we've confirmed the REST step works and returns a valid Response Body, we must now parse that Response Body to extract the field values.

(1) Return to the Flow Designer tab with the Get Trivia Question Action.

(2) Add a Script step after the REST step.

  • Step name: Parse Response

(3) Create two Input Variables.

  • Name: step_input_response_body
  • Value: <<drag the data pill for Response Body in the Data Panel>>
     
  • Name: step_input_status_code
  • Value: <<drag the data pill for Status Code in the Data Panel>>

Define and map input variables for the Parse Response step.

(4) Populate the script field.

(function execute(inputs, outputs) {

if (inputs.step_input_status_code == '200') {

var responseObj = JSON.parse(inputs.step_input_response_body);

outputs.step_output_question = responseObj.result.question;
outputs.step_output_category = responseObj.result.category;
outputs.step_output_difficulty = responseObj.result.difficulty;
outputs.step_output_id = responseObj.result.sys_id;
}

})(inputs, outputs);

Script to parse the response body.

(5) Define the Script step output variables.

  • step_output_question
  • step_output_category
  • step_output_difficulty
  • step_output_id
The Script step output variable values are set in code rather than by using pills in the data panel.

Parse Response step configuration.

(6) Save.

(7) Test the Flow Again. Validate that the step outputs are properly set.

Parse Response step output data.

If the execution details do not show appropriate values for the Script step output variables, review the lab steps to troubleshoot.

7. Map the Step Outputs to Action Outputs

The final step of the process is to map the variables retrieved in the Script step to the Action outputs returned to the user in the Flow.

(1) Return to the Flow Designer tab with the Get Trivia Question Action.

(2) Select Outputs in the Action Outline.

(3) Map the step outputs to Action Outputs by dragging and dropping the data pills from the Script step to the value fields for the Action outputs as shown in the animated graphic.

Map step outputs to Action outputs.

(4) Save the Action.

(5) Test the flow again. Validate that the action outputs are set.

Flow test results showing Action outputs have been set properly.

If the execution details do not show appropriate values for the Action outputs, review the lab steps to troubleshoot.

(6) Once the test is successful, Publish the Action.

8. Add Connection to the method

Connection and Credential Aliases allow you to:

  • Decouple connection information from Actions
  • Define a Connection Alias to use in your Actions
  • Define Connections associated with the alias
  • Choose which connection is active for the alias

In this example, the Get Current traffic action references a Connection alias for the Traffic API. Based on which connection is active for the alias, the appropriate connection will be selected.

9. getAnswer Method API Security

The second method in the Trivia API is getAnswer. The getAnswer method requires authentication on the target application. A service account has been created on the scripting.service-now.com instance with the proper role to access the API.

  • username: xxxxxxxx
  • password: ********

Note that in the source instance, there is a role defined (x_snc_now_trivia.api_user) and an Access Control: 

  • Type: REST_Endpoint
  • Name: /api/x_snc_now_trivia/trivia/getAnswer
  • Requires role: x_snc_now_trivia.api_user

This part replaces the inline connection created in the previous information with a more robust and secure alternative that will be used in the next Activity.

10. Configure Credential to use for Trivia API

(1) Create New Credential.

  • In the main ServiceNow window, navigate to Connections & Credentials > Credentials.
  • New.
  • From the Intercepter that asks for the type of Credentials to create, select Basic Auth Credentials.
  • Complete the Basic Auth Credentials record as follows:
    • Name: api.trivia_user
    • Username: xxxxxxx
    • Password: ********
  •  Submit.

(2) Create a Connection and Credential Alias.

  • Connections & Credentials > Connection & Credential Aliases.
  • New.
  • Complete the record as follows:
    • Name: Trivia
  •  Right-click on the form header and Save.

(3) Create a Connection

  • In the Connections related list, New.
  • Configure the new HTTP(s) Connection record as follows:
    • Name: Trivia Connection
    • Credential: api.trivia_user
    • Connection alias: x_<company_code>_sn_trivia.Trivia
    • Connection URL: http://BASE_URL
    • Submit.

In this exercise, we create a single Connection. In practice, though, if your integration is connecting from your ServiceNow DEV environment to a third-party DEV environment, TEST to TEST, and PROD to PROD, you would create three Connections -- one for each instance in your Company's environment -- DEV, TEST, and PROD. 


Then, you would set the single relevant connection as Active, depending on the instance.


11. Connection Attributes

Early versions of Madrid require that Connection Attributes be defined from the Global scope.

(1) Configure Connection Attributes. 

Re-open the Connection and Credential Alias Trivia record.
In the Connection Attributes related list, select New.
Configure Connection Attributes. 


(2) Switch to Global Scope.

  • From the main ServiceNow window, select Site Settings.


  • One the Developer tab, select the following options:
    • Application: Global
    • Show application picker in header: true
    • Show update set picker in header: true

Select the Global scope and show the Application Picker in the header.


(3) Complete the Connection Attribute form as follows:

  • Type: String
  • Label: Content-Type
  • Column name: u_content-type
  • Max Length: 100
  • Default value: application/json


(4) Right-click on the form header and Save.

Note: Saving rather than submitting will leave the browser open to the same record.

(5) Edit the existing form for the second Connection Attribute:

  1. Label: Accept
  2. Column name: u_accept

(6) Right-click on the form header and Insert.

(7) Switch back to the SN Trivia Spoke application scope.

(8) Open the Trivia Connection Connection record and validate that the attributes appear.

HTTP(s) Connection record with two Attributes defined.

12. Edit getQuestion Action to use Connection and Credential

(1) In the Flow Designer browser tab, open the Get Trivia Question Action.


(2) Update the Call getQuestions Method REST step to use the Connection Alias defined in the previous section.

  • Update fields:
    • Connection: Use Connection Alias
    • Connection Alias: <company_code>_sn_trivia.Trivia
  • In the Request Details section, remove the two headers that were manually defined.


(3) Update the Parse Response Script step to reset the Input Variables by dragging and dropping the respective data pills onto their corresponding Value fields.

Response Body and Status Code data pills dragged to Input Variables Value fields.

Editing the REST step resets the variable mappings.


(5) Save.


13. Test the Action 

Execute the test flow again to validate that the Action still works with the Connection Alias.

The getQuestion method doesn't require the Authentication credential set in this exercise. However, this test validates that the new connection works properly.

14. Create New Action - Get Trivia Answer

The getAnswer method in the API requires authentication. Given valid credentials along with the sys_id of a trivia question, the API returns the corresponding answer.

In this activity, create and test a new Action to retrieve the answer for a Trivia question.

(1) In Flow Designer, create a new Action with the following properties:

  • Name: Get Trivia Answer
  • Application: SN Trivia Spoke
  • Description: Given a valid sys_id for a Trivia question, returns the answer.
  • In Flow Designer, create a new Action with the following properties:


(2) Define the Action Input and Output.

  • Input
    • Label:  Question ID
    • Type: String
    • Mandatory: true
  • Output
    • Label: Answer
    • Value: <leave blank for now>


(3) Add a REST Step to call the getAnswer method.

  • Name: Call getAnswer Method
  • Connection details:
    • Connection: Use Connection Alias
    • Connection Alias: x_<company_code>_sn_trivia.Trivia
  • Request Details:
    • Resource Path: /api/x_snc_now_trivia/trivia/getAnswer
    • HTTP Method: GET
    • Query Parameters:
      • Name: sys_id
      • Value: <<Drag the 'Question ID' data pill from the Input Variables section of the Data pane>>

Question ID data pill dragged to the Query Parameters Value field.


(4) Save.


15. Update the Test Flow and Test the New Action

(1) Refresh the Flow Designer browser window.


(2) Open the Test Trivia Spoke Flow.


(3) Add the Get Trivia Answer action after the Get Trivia Question action. Set the property as follows:

  • Question ID: <<drag-and-drop the Question ID data pill from the '1 - Get Trivia Question' Action onto the field>>
    Add the Get Trivia Answer action after the Get Trivia Question action. Set the property as follows:

Get Trivia Question's "Question ID" data pill dragged to Get Trivia Answer's "Question ID"field.

(4) Save and Test the flow.


(5) Inspect Execution details.

  • Expand the Get Trivia Question Action.
    • Note the question retrieved and the Question ID.
  • Expand Get Trivia AnswerAction and then expand the Steps within the Action. 
    In 'Step 1 - Call getAnswer method [REST]', validate the following:
    • Status code: 200
    • Response Body: contains a well-formed JSON result including an answer.


16. Add a Step to Parse the Response

(1) Open the Get Trivia Answer Action in the Action Designer. 


(2) Add a Script step after the REST step.

  • Name: Parse Response


(3) Define Input Variables:

  • Name: step_input_response_body
  • Value: (drag the 'Response Body' data pill from the Call getAnswer Method Outputs section)
  • Name: step_input_status_code
  • Value: (drag the 'Status Code' data pill from the Call getAnswer Method Outputs section)


(4) Define Output Variable:

  • Name: step_output_answer


(5) Populate Script:

Populate Script:

Try it Validate it

Try writing the code for the Script field yourself using the pseudocode below for guidance.

if (the response from the REST call indicates it was OK) {

     Use the JSON parser to parse the REST call response body.

     Set the value of the step_output_answer output variable

}

(function execute(inputs, outputs) {

//note: your code may differ slightly

  if (inputs.step_input_status_code == '200') {
 
    var responseObj = JSON.parse(inputs.step_input_response_body);
    outputs.step_output_answer = responseObj.result.answer;
   }

})(inputs, outputs);


(6) Compare your Parse Response step with this image. Make any adjustments if necessary.

Completed Get Trivia Answer Parse Response Action step.

17. Map the Step Output to the Action Output and Test the Results

(1) In the Action Outline, select Outputs.


(2) Drag the step_output_answer data pill from the Parse Response section to the value field for the Action output.

Map the Parse Response step output to the Action output.


(3) Save the Action.


18. Test the Action Outputs

(1) Open the Test Trivia Spoke flow.


(2) Test the flow.


(3) Inspect the execution details to validate that the Action Outputs are properly set on the Get Trivia Answer action.


19. Publish the Action

If the Action Outputs look good, return to the Get Trivia Answer action and select Publish.


20. Post Trivia Question to Slack

Incoming Webhooks are a simple way to post messages from external sources into Slack. They make use of normal HTTP requests. The Slack Webhooks Spoke uses webhooks to enable simple integrations to:

  • Post a Message
  • Post Change details
  • Post Incident details
  • Post Problem details

(1) In a new browser tab, navigate to https://slack.com.


(2) Enter an email address and select Get Started.

  • If you already have a Slack workspace you use for testing, skip to step 8.


(3) Create a new workspace.


(4) Enter the confirmation code sent to the email address you used.


(5) Enter a name for the workspace and a project you are working on.


(6) In response to the prompt, Who else is working on this project?, select Skip for now


(7) Select See Your Channel in Slack.


(8) From the Slack workspace, open the Workspace menu and select Administration > Manage apps. 


(9) Select Build.

(10)  In the App features section, select Incoming Webhooks.


(11) Follow the directions in Slack in the Getting started with Incoming Webhooks section.


(12) When you are presented with a Webhook URL, click Continue below.


22. Add a Slack Webhook action to the Test Trivia Spoke Flow

(1) Open the Test Trivia Spoke Flow in Flow Designer.


(2) After the Get Trivia Question action, add a Slack Webhooks Post a Message Action. Configure the Action as follows:

  • Webhook URL: <<paste>>
  • Message: Trivia Question: <<Question>>
  • Username: slackbot
  • Channel: #random


(3) Save and test the flow.


(4) After the Get Trivia Answer action, add a second Slack Webhooks > Post a Message Action to send the Answer to Slack.

Congratulations!  You've integrated with Slack! 

Article Information

Last Updated:2020-06-22 01:26:16
Published:2020-06-22