Software Product Docs

User Guide

Introduction

Http Activity for SCSM allows you to call different API endpoints in a very easy way. By introducing an activity which runs API calls, you can flexibly use your automation as a steps inside your business workflows. All confugiration and endpoints are stored in the CMDB and are triggered from HttpActivities activities within your processes. You can use Http Activities just like you use runbook activities and add them to your Service Request, Change Request, and Release Record templates.

Main Features:

  • Call APIs as part of your Service or Change requests
  • Very secure, solution using RunAs Accounts, all credentials are stored securely in SCSM
  • Configuration stored in Service Manager CMDB
  • Different authentication methods supported out-of-box, including EntraAD and API Key.

Installation

Prerequisites

  • Service Manager 2016 or above
  • Access to endpoints's URL from the workflow server

Installation

The installation is performed using the management pack import functionality of SCSM. Please refer to the Microsoft TechNet Library for more information on how to import management packs:

http://technet.microsoft.com/en-us/library/hh524269.aspx

Follow these steps to install Operaio Http Activity for SCSM:

  1. Log on to SCSM Workflow server using an account with administrative privileges in SCSM. The SCSM Workflow Server is by default the first SCSM Management Server installed.
  2. Copy the \Operaio.HttpActivity.Workflows.dll to the SCSM installation directory. By default, this is C:\Program Files\Microsoft System Center\Service Manager\.
  3. Import the Operaio.HttpActivity.mpb management pack.
  4. Import the itnetX.SCSM.Licensing.Library.mpb Management Pack into your SCSM environment.
  5. Import the itnetX.SCSM.HttpActvityv1.LicenseInfo.mp or the itnetX.SCSM.scsmProdPackv1.LicenseInfo (Bundle license for Productivity Pack) Management Pack into your SCSM environment.
  6. Restart the SCSM Console.

Permissions for other user roles

Operaio Http Activity for SCSM introduces a new class to the CMDB of SCSM. If you are using Http Activities in Service Requests that you publish to your end users using Request Offerings, you need to grant the Enduser role permissions to create instances of this class.

Please follow these steps to grant the required permissions:

  1. Copy the Set-SCSMProfileOperation.ps1 and Set-OpearioHttpActivityPermissions.ps1 files to your SCSM management server (copy both files to the same folder).
  2. Open Set-OpearioHttpActivityPermissions.ps1 in a text editor of your choice.
  3. Find the line $scsmServerName = "localhost" and change the value localhost to the name of your SCSM management server if needed.
  4. Save and close the file.
  5. Run Set-OpearioHttpActivityPermissions.ps1 in PowerShell as an administrator.
  6. Import the Operaio.HttpActivity.Queues.xml Management pack
  7. In your SCSM Console, go to Administration/Security/User Roles, then open the desired User Role, go to "Catalog Item Groups" and provide access to All Http Activity Configurations (Catalog)

How it works

In the following we’re going to describe how to use Operaio Http Activity for Service Requests. The procedure for Change Requests and other work items is the same.

Http Activity contains following parts:

  1. Http Activity Credential. This object contains information about credentials required to access the endpoint. One credential object can be used by several configurations.
  2. Http Activity Configuration. This object contains information about endpoint: URI, methods, headers etc. and link to credential.
  3. Http Activity. This is standard activity that can be used in the SR, CR or PR. It contain link to a configuration.

The Http Activity sends a HTTP Request to the URL specified in the Url property of the configuration object and waits for a response during the time period defined in the Timeout (s) Property.

If the HTTP Method is set to POST, the Body (Parsed) content is sent as body of the HTTP Request.

The Body (Parsed) property is a parsed representation of the Body property and is parsed during the execution of the HTTP Activity which allows to include Properties of SCSM Objects in the body of the HTTP request. More details regarding Body parsing can be found in the Body parsing section further below.

If a response was received its content is added to the Response BodyProperty, and the status code is added to the Response Status Code Property of the Activity.
If the response status code indicates success (1xx, 2xx), the Activity will change its status to Completed, otherwise if the status code does not indicate success, or the specified timeout was reached the activity will change its status to Failed.

If a HTTP Activity failed, refer to its Output for more details why it failed.

A response status code of 202 indicates that the API Endpoint is working asynchronously and a response must be polled from the URL returned by the API in the response location header. In this case the HTTP Activity will attempt to poll for a response automatically until the specified timeout is reached.

Azure Automation Runbooks typically return the status code 202 but do not provide any Url in the location header. To allow the HTTP Activity to poll for the status of an Azure Automation Runbook some additional configuration is required. Refer to the section Azure Automation Runbook for more details.

All HTTP Requests are sent anonymously without any authentication unless a credential object is selected for the Credential property of the HTTP Activity. Refer to the Authentication Section further below for more details regarding authentication.

Create Http Activity Credential in SCSM

The Http Activity Credentials, which you can use for the Http Activity configuration, are placed in the console under Administration -> Operaio HTTP Activity Configuration -> HTTP Activity Credentials. Here you can add and manage your Http Activity Credentials:

To create a new Http Activity Credential, follow the steps below:

  1. Move to the HTTP Activity Credentials view under Administration -> Operaio HTTP Activity Configuration
  2. Make a right click on HTTP Activity Credentials or use Create HTTP Activity Credentials in the Action Pane
  3. Enter a Name and optionally a Description
  4. Choose Type, depends on select type you will have different fields.

Note: for EntraID Application Certificate the certificate path is related of SCSM Workflow server.

Create Http Activity Configuration in SCSM

The Http Activity Configuration, which you can use for the Http Activity, are placed in the console under Administration -> Operaio HTTP Activity Configuration -> HTTP Activity Configurations. Here you can add and manage your Http Activity Configuration:

To create a new Http Activity Configuration, follow the steps below:

  1. Move to the HTTP Activity Configurations view under Administration -> Operaio HTTP Activity Configuration
  2. Make a right click on HTTP Activity Configurations or use Create HTTP Activity Configurations in the Action Pane
  3. Enter a Name and optionally a Description
  4. Choose HTTP method, set url and content type header
  5. Choose Credential object if this method requires authentication
  6. Choose Is Azure Automation Runbook if you want to use it (see section below for more detailed explanation)
  7. Set Body (see section below) and headers if necessary

Body parsing

Before the HTTP Activity sends the HTTP request, the content of the property Body is parsed and placed in the Body (Parsed) property. the parsed content is then sent as body of the HTTP request if the selected HTTP Method is POST.
During this body parsing process, the HTTP Activity checks if the Body property contains any tokens in the format of @[token] and replaces these tokens as explained in the table below:

Token Example Description
Property @[Title] Is replaced with a property of the current Activity. The example would be replaced with the Title of the current HTTP Activity.
Parent Property @[{Parent}/Title] The {Parent} part of the token looks for a parent WorkItem, then looks for the property defined after /. In this case the token would be replaced with the Title of the current Activity's Parent WorkItem. Note that {Parent} can be used multiple time, e.g. @[{Parent}/{Parent}/Title]
Root Property @[{Root}/Title] The {Root} part of the token looks for the top most parent WorkItem which is usually the Service Request, or Change Request containing the Activity, then looks for the property defined after /. In this case the token would be replaced with the Title of the current Activity's root WorkItem
User Input @[{Root}/{UserInput}] The {UserInput} part of the token is replaced with a JSON representation of the UserInput property of any WorkItem.
User Input Answer @[{Root}/{UserInput}/Describe your issue] In addition to just use the User Input token to add the complete User Input, you may append a / followed by the desired Answer title after the {UserInput} part of a token to get only the Answer of this specific question of a user Input.
Example

For an example, consider the following Body: 

{
    "activityTitle": @[Title],
    "incidentDescription": @[{Root}/Description],
    "userInput": @[{Root}/{UserInput}],
    "problemDescription": @[{Root}/{UserInput}/Describe your issue]
}

After the parsing process, the Body (parsed) representation of the body above would look like this: 

{
    "activityTitle": "HTTP Request for Teams message",
    "incidentDescription": "Generic Request",
    "userInput": {
        "Provide a short description": "Printer not working",
        "Describe your issue": "The Printer at the entrance is not working. Something about magenta...",
        "How urgent is your issue?": "Very much so!"
    },
    "problemDescription": "The Printer at the entrance is not working. Something about magenta..."
}

Adding a Http Activity

After you created a Http Activity Configuration in SCSM, you can use this for a Http Activity. We are going to describe how to add a Http Activity to a Service Request. For Change Request and Release Record and other Work Items it is the same.

  1. Create a new Service Request from a template and fill out the required fields, or open an existing Service Request template.
  2. Go to the Activities tab and press the + button to add a new Activity
  3. Select the Default Http Activity
  4. Enter a Title and optional a Description
  5. In the Configuration section, use the … button to browse for your Http Activity Configuration.
  6. Select the Http Activity Configuration you want to use for this activity and select it:

    By pressing the … button you also have the possibility for an Advanced Search, where you can specify more filters with the available properties:
  7. After the selection of the Http Activity Configuration you can save the activity.
  8. Add more activities if needed and then save the Service Request and the execution of the activities will start.

Authentication

API Key

If you your request must be authenticated using API Key then this is possible by using the corresponding Http Activity Credentials configuration.

  1. Create new Http Activity Credentials as shown above, choose Type: API Key
  2. Enter attribute name for the API key
  3. Choose location (Header or URL Parameter) where the attribute must be placed.

Once you have created the Http Activity Credential Object in SCSM you can relate it to any HTTP Activity Configuration using the Credential Instance picker to authenticate the HTTP Request.

Azure Service Principal

In some cases your HTTP Requests must be authenticated using a Bearer Token of an Azure Service Principal (Azure App Registration), for example if you wish to run a Power Automate Flow which allows only users of its tenant to run the flow.
The HTTP Activity allows to authenticate its HTTP requests using a Bearer Token retrieved from Azure EntraID using either a client secret, or a client certificate.

Client Secret

Follow the steps below to configure a HTTP Activity to authenticate its requests using a Bearer token acquired using a client secret:
1. In your Azure Portal, open the desired AppRegistration, create a new Client secret and copy the secret value 2. Create new Http Activity Credentials as shown above, choose Type: EntraID Application Secret 4. On the Configuration section provide the following details and click OK:
a. Tenant Id: The Tenant Id of the tenant containing the AppRegistration
c. Application (Client) Id: The Client Id of your AppRegistration
d. Click New button right from RunAs Account picker e. Enter meaningful Display Name (can be any), leave Domain as 'None', put UserName as Client ID and paste secrete from step 1 as Secrete. b. Scope: The required scope (e.g. https://graph.microsoft.com/.default)

Once you have created the Http Activity Credential Object in SCSM you can relate it to any HTTP Activity Configuration using the Credential Instance picker to authenticate the HTTP Request.

Update existing Client Secret

When your Client secret expires you can update it in the RunAs Accounts view (Administration\Security\Run As Accounts view in the SCSM Console).

Client Certificate

Follow the steps below to configure a HTTP Activity to authenticate its requests using a Bearer token acquired using a client certificate:
1. On the the SCSM Workflow server, right-click PowerShell and select Run as different user
2. Provide the credentials of the Workflow Service Account to open PowerShell
3. Execute the following script to create a new Certificate, Certificate Credentials SCSM Object, and to export the new Certificate: 

Import-Module HTTPActivity  
New-Certificate -CertificateName "Some Name" -Location "Cert:\LocalMachine\My" -ExportPath "C:\Temp" -TenantId "<GUID of your Azure Tentant>" -ApplicationId "<GUID of the Application (Client)>" -Scope "https://graph.microsoft.com/.default"
  1. Find the certificate in the Folder specified as -ExportPath parameter above.
  2. Open the desired AppRegistration in the Azure Portal and upload the certificate to this AppRegistration
  3. In the SCSM Console, create new Http Activity Credentials as shown above, choose Type: EntraID Application Secret
  4. Verify that a new Entra ID Client Certificate Object has been created with the values specified in the powershell script
  5. Paste the path adn the certificate name from step 3

Once you have created the Http Activity Credential Object in SCSM you can relate it to any HTTP Activity Configuration using the Credential Instance picker to authenticate the HTTP Request.

Update existing Client Certificate

To update an existing Client Certificate Object in SCSM whose Certificate is expired, follow the steps below:
1. On the the SCSM Workflow server, right-click PowerShell and select Run as different user
2. Provide the credentials of the Workflow Service Account to open PowerShell
3. Execute the following script to create a new Certificate, Certificate Credentials SCSM Object, and to export the new Certificate: 

Import-Module HTTPActivity  
New-Certificate -SMCredentialId "CRED123(ID of object in SCSM)"  -ExportPath "C:\Temp"
  1. Find the certificate in the Folder specified as -ExportPath parameter above.
  2. Open the desired AppRegistration in the Azure Portal and upload the certificate to this AppRegistration

Azure Automaltion Runbooks

Running Azure Automation Runbooks using webhooks does not require any additional authentication. In fact, the request Url of the webhook contains a key to authenticate your request. However, since Azure Automation Runbooks do not provide any Url to poll for the Runbook's Job status the HTTP Activity must use an Azure Service Principal to poll for the Job status using the Azure Management API. This requires some additional configuration to work.

Note that polling for a Runbook's job status is not required for the HTTP Activity to complete. If the additional configuration for polling Azure Automation Runbook Job status is omitted the Activity will complete immediately with the response status code 202. In this case you do not have any feedback if your Runbook was succesfull, or not.

Follow these steps to allow for polling a Azure Automation Runbook's job status:
1. Create Http Activity Credential as described above with the Scope property set to https://management.azure.com/.default. 2. Next, open your AppRegistration in the Azure Portal and go to API permissions
3. Add the Permission user_impersonation found in Azure Service Management under Delegated permissions
4. Grant Admin consent for the newly added permission
5. Open the Automation Account containing the desired Runbook(s) in the Azure Portal
6. Go to the Access control (IAM) section of your Automation Account
7. Select Add Role assignment
8. Select the Role Reader in the Roles section and move to Members
9. Click + Select members and choose your previously configured Service Principal (AppRegistration) as Member.
10. Click Review + assign
11. In the SCSM Console, go to Administration -> Operaio HTTP Activity Configuration -> HTTP Activity Configurations
12. Click Create HTTP Activity Configuration in the taskbar and create new configuration as described above with the Is Azure Automation Runbook property set to true 13. On the Azure Automation Settings section, provide the following details, then click OK:
a. Account Name: The Name of your Azure Automation Account as displayed in the Azure Portal
b. Resource Group: The Name of the Resource Group containing your Automation Account, as displayed in the Azure Portal
c. Subscription Id: The GUID of the Subscription containing your Automation Account
14. In the HTTP Activity which starts your Azure Automation Runbook, select the HTTP Activity Configuration object created in step 12-13 using the Instance picker